Purchase label

The final step is to purchase the shipment. This will generate your shipping label.

There are two ways to purchase a shipment.

  1. You can purchase the shipment object you created in the last step. This is useful when you want to find the best rate and service level for your shipment.
  2. You can purchase a label without a shipment object in a single call . This is useful when you what to immediately create your label.

HTTP Method

POST

URL

Copy
Copied
https://api.goshippo.com/transactions/

Purchase from created Shipment

This is a flow where we first create a shipment object (and get rates for a given shipment). Then, we purchase a label for the provided rate.

Request Payload

Parameter Description
rate* ‘object_id’ of the rate object we get in the create shipments call response.
parcels Array of parcels
Example with 2 parcels
label_file_type Allowed values:PDF, PDF_A4, PDF_A6, PDF_4x6, PDF_4x8, PDF_SINGLE_8X11, PDF_2.3x7.5, PNG, PNG_2.3x7.5, ZPLII

Multiple parcels payload example

Copy
Copied
"parcels": [
       {
           "length": "10",
           "width": "8",
           "height": "10",
           "distance_unit": "cm",
           "weight": 2,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               },
               {
                   "title": "Hippo Magazines -2",
                   "variant_title": "June edition",
                   "sku": "HM-1234",
                   "hs_code": "21234",
                   "quantity": 1,
                   "amount": "15.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       },
       {
           "length": "10",
           "width": "5",
           "height": "8",
           "distance_unit": "cm",
           "weight": 3,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines - 2",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       }
   ]

Example

Request Sample

Copy
Copied
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken shippo_live_***’ \
--header 'Content-Type: application/json' \
--data-raw '{
   "rate": "74800d3fa6734d88ad65b88dc4ed2008",
   "label_file_type": "PDF",
   "async": false
}'

Response Sample

Copy
Copied
{
  {
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2022-12-14T16:31:14.268Z",
    "object_updated": "2022-12-14T16:31:21.494Z",
    "object_id": "b470b8cae35544728279664d33cd3abb",
    "object_owner": "nataliya_eng@shippo.com",
    "test": true,
    "rate": "562f1c1a920949789702b67c24d514fe",
    "tracking_number": "2908922",
    "tracking_status": "UNKNOWN",
    "eta": null,
    "tracking_url_provider": "https://apgecommerce.com/?page_id=18102908922",
    "label_url": "https://dev-qa-deliver.shippodev.com/b470b8cae35544728279664d33cd3abb.pdf?Expires=1702571481&Signature=X2I6CEAXakpxb3GFiwxa0RwYezqOpMRnRsK55WBYkMrcKB5KttFBZumgjUfLxDmBXjHMDyaX9EBT6iYS4LQXPgu2EGguePYIZzp9vCeSjjzr4fsqR7Qz-g3URrGn~ljI5fa2Cp4kXJ2V9lH7GaPGQkzzRQa7YDBP7JT0Eo3R1gqZt8i3eJin97We-r4hw8DL70rAp5mdPNNZHydg2NQBuHWCLbW6D4a~0GaARlU~dsMqGzKCrfc-MPgCiKYI8FOgLH3yY9mVM7pWILB-MWZ3MOX0EOnnKyHROskBPyS4XbpYGC~kNo2ZihwwZyO2zSHg-AwdTXMEV3XZSOFSYX0lNA__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "commercial_invoice_url": "https://dev-qa-deliver.shippodev.com/ci_b470b8cae35544728279664d33cd3abb.pdf?Expires=1702571481&Signature=E5ECWAA1x3oKrDN-2zuhwrIjlsX3Z3fr7dfFEqpeeSuTAhn9DJXlM3dMm~ecpuoLn5McoEfFtg0ZnSIQLrlqqJvnbqfUNpPgUrZsjnABpK7tJeCqq8CQQB2ttar8HMNuPe7oSJlljrcfAA93-mjuI~1ddT7rTGOvazIizawpSKmppbPjJdzuvMS~s2YHaaIFQXMl1vFK0PDI6TyKAAJKIpEs3FOaqDnTSXZi1Ym0g3JIQEq2~kNJ6oEZ5jLc-fciO7rwh4qJApSbpAbMic6YkHkrbN0YEbY9tSgCwM7sLwJSnndFqY~6-XvveLSfwRmvNXVZ58qB9FZ82~~qS8Pi~g__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "messages": [],
    "order": null,
    "metadata": "",
    "parcel": "bf4356b1eda94d30be17662df1ed6e4e",
    "billing": {
        "payments": []
    },
    "qr_code_url": null
}


}

Purchase label in one call

This is a flow where we create a shipment object from the request payload and return label for it in one call. This is useful if you already know which carrier and service you want to use.

Request Payload

Parameter Description
shipment* Refer to the Shipment object.
carrier_account* object_id of the carrier account to be used for purchasing this label. This carrier account object_id is available when an account is created.
servicelevel_token* Name of the service level to use. For APG must be one of the following:
epacket
epacket_plus
eparcel_premium
apg_eparcel_expedited
These are case sensitive.
label_file_type* Allowed values:
PDF
PDF_A4
PDF_A6
PDF_4x6
PDF_4x8
PDF_SINGLE_8X11
PDF_2.3x7.5
PNG
PNG_2.3x7.5
ZPLII

Shipment

Parameter Description
address_from* Refer to the Address object
address_to* Refer to the Address object
parcels* List of Parcel objects. Refer Parcel object
extra Refer to the Extra object

Example

Request sample for label creation with single call

Copy
Copied
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken shippo_live_******' \
--header 'Content-Type: application/json' \
--data-raw '{
   "shipment": {
       "object_purpose": "PURCHASE",
       "address_from": {
           "object_purpose": "PURCHASE",
           "name": "Shipping Mgr",
           "company": "Shippo",
           "street1": "4727 W 1st St",
           "street2": "",
           "city": "New York",
           "state": "NY",
           "zip": "10005",
           "country": "US",
           "phone": "12028642186",
           "email": "nataliya_eng@shippo.com",
           "is_residential": false
       },
       "address_to": {
           "object_purpose": "PURCHASE",
           "name": "Nata Lee",
           "street1": "1720 S Grand Ave",
           "city": "Sydney",
           "state": "VIC",
           "zip": "3026",
           "country": "AU",
           "phone": "+1 666 147 2589",
           "email": "nata@gmail.com",
           "metadata": "",
           "is_residential": true
       },
       "parcels": {
           "length": "10",
           "width": "8",
           "height": "10",
           "distance_unit": "cm",
           "weight": 2,
           "mass_unit": "kg",
           "line_items": [
               {
                   "title": "Hippo Magazines",
                   "variant_title": "June edition",
                   "sku": "HM-123",
                   "hs_code": "2123",
                   "quantity": 1,
                   "amount": "12.10",
                   "currency": "USD",
                   "weight_unit": "kg",
                   "manufacture_country": "US"
               }
           ]
       },
       "customs_declaration": {
           "contents_type": "MERCHANDISE",
           "certify": true,
           "certify_signer": "Test Certifier",
           "incoterm": "DDP",
           "is_vat_collected": "paid",
           "exporter_identification": {
               "tax_id": {
                   "type": "IOSS",
                   "number": "TAXNUMBER12345"
               }
           },
           "items": [
               {
                   "description": "shirt",
                   "quantity": 1,
                   "net_weight": "1",
                   "mass_unit": "oz",
                   "value_amount": "10",
                   "value_currency": "USD",
                   "origin_country": "US",
                   "tariff_number": "",
                   "metadata": "ts mi"
               }
           ]
       },
       "extra": {
           "reference_1": "123456780",
           "carrier_hub_id": "ORD"
       },
       "metadata": "Customer ID 123456",
       "async": false
   },
   "label_file_type": "PDF",
   "carrier_account": "{{APG_ACC}}",
   "servicelevel_token": "eparcel_premium"
}’

Response sample

Copy
Copied
{
    "object_state": "VALID",
    "status": "SUCCESS",
    "object_created": "2022-12-14T16:28:24.551Z",
    "object_updated": "2022-12-14T16:28:37.611Z",
    "object_id": "b194569f472c4dd9b9175ce498bcb914",
    "object_owner": "nataliya_eng@shippo.com",
    "test": true,
    "rate": {
        "object_id": "562f1c1a920949789702b67c24d514fe",
        "amount": "9.92",
        "currency": "USD",
        "amount_local": "14.45",
        "currency_local": "AUD",
        "provider": "APG",
        "servicelevel_name": "eParcel premium",
        "servicelevel_token": "eparcel_premium",
        "carrier_account": "2edac0dddcfc4416b2708cc10b2d11e0"
    },
    "tracking_number": "2908920",
    "tracking_status": "UNKNOWN",
    "eta": null,
    "tracking_url_provider": "https://apgecommerce.com/?page_id=18102908920",
    "label_url": "https://dev-qa-deliver.shippodev.com/b194569f472c4dd9b9175ce498bcb914.pdf?Expires=1702571314&Signature=AevKXrScFoYs8a1olpQIAFM0trtLm5ZFiXa4PQwUvCR38AUBLzoPN87xwafHLflD5LgvhvIVsQ9DZ~qR8-UE~Ke9cVciH3HsaU5GTHUEDGWabjghi8NJim4lARzJH38SrwQtRGlhVse9EIgvDt9GGoptyPtz2ypRuvFUhKnbGnSV2E2Qdvmw5rJqdzHNT4eoIZMWWgrh9fBdismZ0CnplnxzaGpxXygUKzbinii~EAzHLsaEYY-AdiaSFi3TJ7agzQj3aoGVjmtdaup20aJ5BGsYcQacNayW-1SlIrrBbtVeYRC8Jm3SyGIgntsAGfO93Zfnrc~CQAsCyjlR0dS1tw__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "commercial_invoice_url": "https://dev-qa-deliver.shippodev.com/ci_b194569f472c4dd9b9175ce498bcb914.pdf?Expires=1702571317&Signature=iR-md7Vs8i8LxFokLV8TsnvHACaRn-Xj0XxS1djr9IKHYb17LoQEkqlLW7rrj5xXqroRTAxCpRtiFJuu2DclAkMxpdUsise8p4lShODyL0IzU23hyvMWaTnHgPF1rc1PCIsmn-uUvvwJ2je4FhF3rlOj2JsKKnuY0binBsQyyTbwvqhJ1DQ2IleMd85X8Oljj22W5kOop3aVaAw~-laRzAm5Qghot-clCeDvYNDQnbtDKumFE3-K-yGDhudljmlyS3mgnScFz5k0o2Je8bBGTwhmRPTl32O4Tq17QCrbW7v5CwN~bDl6qzrl2efAsns1m74fUfsYeQpausts-ueWpw__&Key-Pair-Id=APKAJKRDBHOMWKB2OAVQ",
    "messages": [],
    "order": null,
    "metadata": "",
    "parcel": "bf4356b1eda94d30be17662df1ed6e4e",
    "billing": {
        "payments": []
    },
    "qr_code_url": null
}