Skip to content
Carriers/
/
3. Purchase a label
Last updated

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

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

ParameterDescription
rate*‘object_id’ of the rate object we get in the create shipments call response.
parcelsArray of parcels
Example with 2 parcels
label_file_typeAllowed 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

"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

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

{
  {
    "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

ParameterDescription
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

ParameterDescription
address_from*Refer to the Address object
address_to*Refer to the Address object
parcels*List of Parcel objects. Refer Parcel object
extraRefer to the Extra object

Example

Request sample for label creation with single call

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

{
    "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
}
Previous page
Next page