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
  2. You can purchase a label without a shipment object in a single call

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.
label_file_type* Allowed values: PDF, PDF_A4, PDF_A6, PDF_4x6, PDF_4x8, PNG, ZPLII
async Set to true if you want to poll for the result and receive faster response
Copy
Copied
Note: Parameters with an * are mandatory

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": "975445f117db48e5b3e85cebebe87ee0",
    "async": false,
    "label_file_type": "PDF_A4"
}'

Response Sample

Copy
Copied
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-11-10T23:47:18.278Z",
   "object_updated": "2022-11-10T23:47:20.948Z",
   "object_id": "cbc1a12243db44b9ae56ef3ca502b8c3",
   "object_owner": "test-use@shippo.com",
   "test": false,
   "rate": "975445f117db48e5b3e85cebebe87ee0",
   "tracking_number": "00024000110003001",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "you_will_find_your_tracking_url_here",
   "label_url": "you_will_find_your_label_url_here",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "e54ef8c0a27c451690bca6f3b6491264",
   "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

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. Must be one of the following: colissimo_home, colissimo_pick_up_point, colissimo_return_mainland_france. These are case-sensitive.
label_file_type* Allowed values: PDF, PDF_A4, PDF_A6, PDF_4x6, PDF_4x8, PNG, 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
customs_declaration* Refer to the Customs declaration object. Required for international shipments

Examples

Request sample for a domestic shipment

Copy
Copied
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken shippo_live_******' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shipment": {
        "address_from": {
                "name": "Èmile Zola",
                "company": "Palais Jacques Coeur",
                "street1": "3 Place du Berry",
                "street2": "Rue Jacques Coeur 756",
                "city": "Cher",
                "state": "Bourges",
                "zip": "18000",
                "country": "FR",
                "phone": "+1888-999-1500",
                "email": "Picardie@shippo.com"
        },
        "address_to": {
            "name": "Chapelaine Carnot",
            "company": "Louis Ulbach",
            "street1": "8 Rue de La Vicomté",
            "street2": "Rue de la Pierre",
            "city": "Aube",
            "state": "Troyes",
            "zip": "10000",
            "country": "FR",
            "phone": "+18889575900",
            "email": "Chapelaine@shippo.com"
        },
        "parcels": [{
            "weight": "1",
            "length": "5",
            "width": "4",
            "height": "1",
            "distance_unit": "cm",
            "mass_unit": "kg"
        }],
        "extra": {
                "reference_1": "Ship.Label_Chrono_Ok"
        }
    },
  "label_file_type": "PNG",
  "servicelevel_token": "colissimo_home",
  "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
}'

Response sample for a domestic shipment

Copy
Copied
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-11-11T00:19:44.077Z",
   "object_updated": "2022-11-11T00:19:46.446Z",
   "object_id": "c42aabb1755d462395e83150ad74f84b",
   "object_owner": "test-user@shippo.com",
   "test": false,
    "rate": {
        "object_id": "e9ef8e278a4949d697cc48fead716033",
        "amount": "8.14",
        "currency": "EUR",
        "amount_local": "8.14",
        "currency_local": "EUR",
        "provider": "Colissimo",
        "servicelevel_name": "Domicile",
        "servicelevel_token": "colissimo_home",
        "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
    },
   "tracking_number": "AT00024000110003000",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "you_will_find_your_tracking_url_here",
   "label_url": "you_will_find_your_label_url_here",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "56sdfhjlbde8d41dd805de409e7b8a729",
   "billing": { 
       "payments": []
   },
   "qr_code_url": null
}

Request sample for an international shipment

Copy
Copied
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken shippo_live_******' \
--header 'Content-Type: application/json' \
--data-raw '{
    "shipment": {
        "address_from": {
            "name": "Èmile Zola",
            "company": "Palais Jacques Coeur",
            "street1": "3 Place du Berry",
            "street2": "Rue Jacques Coeur 756",
            "city": "Cher",
            "state": "Bourges",
            "zip": "18000",
            "country": "FR",
            "phone": "+1888-999-1500",
            "email": "Picardie@shippo.com"
        },
        "address_to": {
            "name": "Mr. Hippo",
            "street1": "24 Endell",
            "city": "London",
            "state": "",
            "zip": "W1D 4HS",
            "country": "GB",
            "phone": "01159 663055",
            "email": "mrhippo@shippo.com"
        },
        "parcels": [
            {
                "weight": "1",
                "length": "5",
                "width": "4",
                "height": "1",
                "distance_unit": "cm",
                "mass_unit": "kg"
            }
        ],
        "customs_declaration": {
            "invoiced_charges": {
                "total_shipping": "10.00",
                "currency": "EUR"
            },
            "contents_type": "MERCHANDISE",
            "contents_explanation": "T-Shirt purchase",
            "invoice": "#123123",
            "notes": "Notes here",
            "certify": true,
            "certify_signer": "Test User",
            "incoterm": "DDU",
            "items": [
                {
                    "description": "shirt",
                    "quantity": 1,
                    "net_weight": "7",
                    "mass_unit": "oz",
                    "hs_code": "61091000",
                    "sku_code": "A333BFEQA",
                    "value_amount": "10",
                    "value_currency": "EUR",
                    "origin_country": "FR"
                }
            ]
        },
        "extra": {
            "reference_1": "Ship.Label_Chrono_Ok"
        }
    },
    "label_file_type": "PNG",
    "servicelevel_token": "colissimo_home",
    "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
}'

Response sample for an international shipment

Copy
Copied
{
   "object_state": "VALID",
   "status": "SUCCESS",
   "object_created": "2022-11-11T00:19:44.077Z",
   "object_updated": "2022-11-11T00:19:46.446Z",
   "object_id": "c42aabb1755d462395e83150ad74f84b",
   "object_owner": "test-user@shippo.com",
   "test": false,
    "rate": {
        "object_id": "e9ef8e278a4949d697cc48fead716033",
        "amount": "8.14",
        "currency": "EUR",
        "amount_local": "8.14",
        "currency_local": "EUR",
        "provider": "Colissimo",
        "servicelevel_name": "Domicile",
        "servicelevel_token": "colissimo_home",
        "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5"
    },
   "tracking_number": "AT00024000110003000",
   "tracking_status": "UNKNOWN",
   "eta": null,
   "tracking_url_provider": "you_will_find_your_tracking_url_here",
   "label_url": "you_will_find_your_label_url_here",
   "commercial_invoice_url": null,
   "messages": [],
   "order": null,
   "metadata": "",
   "parcel": "56sdfhjlbde8d41dd805de409e7b8a729",
   "billing": { 
       "payments": []
   },
   "qr_code_url": null
}

Response

A successful response includes all the details about your purchased shipment including tracking details and a link to your shipping label.