Create shipment

The second step is to create a shipment. The shipment includes all the details about the item you are shipping including

the “from” and “to” addresses
the parcel details
extra parameters
customs declaration, that are required for international shipments

Creating a shipment automatically generates a list of shipping rates that you can use to select the best shipping option for you. In these examples, you will see rates from APG but you can also generate rates from other carriers using the carrier_accounts parameter.

HTTP Method

POST

URL

https://api.goshippo.com/shipments/

Request Payload

Parameter	Description
address_from*	Refer to the Address object
address_to*	Refer to the Address object
parcels*	Refer to the Parcel object
extra	Refer to the Extra object
customs_declaration*	Refer to the Customs declaration object. Required for international shipments
carrier_accounts	An array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. This carrier account object_id is available when an account is created. See carrier account response sample. If no carrier account object_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the ‘active’ field set.
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`
metadata	Possible to use to define customer ID
async	If set to false in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.

Note: Parameters with an * are mandatory

Objects

Address

Parameter	Description
Name*	First and Last name of the addressee
Company	Company Name (if applicable)
Street1*	First street line, 35 character limit. Usually street number and street name
Street2	Second street line, 35 character limit
City*	Name of a city
Zip*	Postal code of an address
State*	State/Province values are required for shipments from/to the US.
Country*	ISO 2 country code
phone	Phone number of the addressee
email	E-mail address of the contact person, RFC3696/5321-compliant
is_residential	`true`(if address is residential) or `false` if not.

Parcel

Parameter	Description
length*	Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted
width*	Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted
height*	Height of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted
distance_unit*	“cm” “in” “ft” “mm” “m” “yd”
weight*	Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted
mass_unit*	“g” “oz” “lb” “kg”
line_items*	Array of object for one or several line items. This section contains the line items’ details that were packed in the relevant parcel. See line items object
custom_declaration*	Custom declaration support. See customs declaration object

Line Items

Parameter	Description
title*	Description of product
variant_title	Additional description
SKU*	Product’s stock keeping unit
hs_code*	hs_code
quantity	quantity
amount*	Amount
currency*	Currency
weight_unit*	Weight unit for this item’s type
manufacture_country*	ISO 2 country code

Customs Declaration

Note

If shipping to AU or NZ using APG, you must pass an ARN on the tax identifiers using Exporter_identification.tax_id in your customs declaration.
If shipping to an EU country using APG, you must pass an IOSS value on the tax identifiers using Exporter_identification.tax_id in your customs declaration.

Parameter	Description
contents_type	Type of goods of the shipment. Possible values: `DOCUMENTS` `GIFT` `SAMPLE` `MERCHANDISE` `HUMANITARIAN_DONATION` `RETURN_MERCHANDISE` `OTHER`
certify	Expresses that the certify_signer has provided all information of this customs declaration truthfully. Boolean value: `true` or `false`.
certify_signer	Name of the person who created the customs declaration and is responsible for the validity of all information provided.
incoterm	The incoterm reference of the shipment. Possible values: `DDU` (For shipments where you expected to use `DAP`, use `DDU` instead) `DDP`
is_vat_collected	Indicates whether the shipment’s destination VAT has been collected. Required for AU/NZ destinations if exporter_indentification.number is not empty and exporter_indentification.tax_id = “ARN” Boolean value: true or false.
Exporter_identification	Exporter_identification should be here as number and tax_id. `number` - means tax identification number. `tax_id` - type of tax identification. Possible types of tax_id: `EIN` - Employer Identification Number, also known as a Federal Tax Identification Number. `VAT` - Value Added Tax identification number. `IOSS` - Import One-Stop Shop `ARN` - Australian Taxation Office Reference Number Example: “exporter_identification”: “tax_id”: “type”: “IOSS”, “number”: “TAXNUMBER12345”
items*	Array of Customs Items object_ids Example: “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 Details

Parameter	Description
extra: reference_1	APG OrderNo. The primary shipment reference used by your organization. It can be the sales order number, the shipment number or any other delivery identification. Optional text to be printed on the shipping label. Up to 50 characters
extra: carrier_hub_id	Identifies the carrier injection site (APG HAWBOrigin). You should only specify this for shipments originating from USA. The following codes are supported hub IDs: `JFK`, `LAX`, `MIA`, `ORD`, `ATL`.

Response Code

201

Examples

Request Sample

cURL

curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "object_purpose": "PURCHASE",
   "shipment_date": "2022-12-10T23:59:59Z",
   "address_from": {
       "object_purpose": "PURCHASE",
       "name": "Shipping Manager",
       "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",
       "company": "Shipper -2 , Inc.",
       "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"
           },
           {
               "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"
           }
       ]
   },
   "customs_declaration": {
       "contents_type": "MERCHANDISE",
       "non_delivery_option": "ABANDON",
       "certify": true,
       "certify_signer": "Test Certifier",
       "incoterm": "DDP",
       "is_vat_collected": "",
       "exporter_identification": {
           "tax_id": {
               "type": "ARN",
               "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": "1234567890",
       "carrier_hub_id": "ORD"
   },
   "metadata": "Customer ID 123456",
   "async": false,
   "label_file_type": "PDF",
   "carrier_accounts": [
     "{{APG_ACC}}"
   ]
}’

Response Sample

 {
    "carrier_accounts": [
        "2edac0dddcfc4416b2708cc10b2d11e0"
    ],
    "object_created": "2022-12-09T13:27:24.058Z",
    "object_updated": "2022-12-09T13:27:24.058Z",
    "object_id": "f2f1bf3f4a004ce2b609f7c19251b15d",
    "object_owner": "nataliya_eng@shippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "8d50f611519e4efb89934cc3ee1905c0",
        "is_complete": true,
        "name": "Shipping Manager",
        "company": "",
        "street_no": "",
        "street1": "4727 W 1st St",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "New York",
        "state": "NY",
        "zip": "10005",
        "country": "US",
        "phone": "12028642186",
        "email": "nataliya_eng@shippo.com",
        "is_residential": false,
        "test": true
    },
    "address_to": {
        "object_id": "36e3b76eece54237aa7a1b33bc6b834b",
        "is_complete": true,
        "name": "Nata Lee",
        "company": "Shipper -2 , Inc.",
        "street_no": "",
        "street1": "1720 S Grand Ave",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "Sydney",
        "state": "VIC",
  "zip": "3026",
        "country": "AU",
        "phone": "0016661472589",
        "email": "nata@gmail.com",
        "is_residential": true,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2022-12-09T13:27:23.751Z",
            "object_updated": "2022-12-09T13:27:24.413Z",
            "object_id": "9510a3eeb03245a4b53703019894b323",
            "object_owner": "nataliya_eng@shippo.com",
            "template": null,
            "extra": {},
            "length": "10.0000",
            "width": "10.0000",
            "height": "8.0000",
            "distance_unit": "cm",
            "weight": "2.0000",
            "mass_unit": "kg",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [
                "ed20bbd90c4248cd9ab3ea4836a9d407",
                "964b6b076b034b64b911cb18afbb489a"
            ],
            "test": true
        }
    ],
    "shipment_date": "2022-12-10T23:59:59Z",
    "address_return": {
        "object_id": "8d50f611519e4efb89934cc3ee1905c0",
        "is_complete": true,
        "name": "Shipping Manager",
        "company": "",
        "street_no": "",
        "street1": "4727 W 1st St",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "New York",
        "state": "NY",
        "zip": "10005",
        "country": "US",
        "phone": "12028642186",
        "email": "nataliya_eng@shippo.com",
        "is_residential": false,
"test": true
    },
    "alternate_address_to": null,
    "customs_declaration": {
        "object_created": "2022-12-09T13:27:23.959Z",
        "object_updated": "2022-12-09T13:27:23.959Z",
        "object_id": "66b6b7ee811b44a7abddaa4307181afd",
        "object_owner": "nataliya_eng@shippo.com",
        "object_state": "VALID",
        "address_importer": null,
        "certify_signer": "Test Certifier",
        "certify": true,
        "items": [
            "249fa7da308d4e41b2af4fed32368d81"
        ],
        "non_delivery_option": "ABANDON",
        "contents_type": "MERCHANDISE",
        "contents_explanation": "",
        "exporter_reference": "",
        "importer_reference": "",
        "invoice": "",
        "commercial_invoice": false,
        "license": "",
        "certificate": "",
        "notes": "",
        "eel_pfc": "",
        "aes_itn": "",
        "disclaimer": "",
        "incoterm": "DDP",
        "metadata": "",
        "test": true,
        "duties_payor": null,
        "b13a_filing_option": "",
        "b13a_number": "",
        "invoiced_charges": null,
        "exporter_identification": {
            "tax_id": {
                "type": "ARN",
                "number": "TAXNUMBER12345"
            }
        },
        "is_vat_collected": false
    },
    "extra": {
        "reference_1": "1234567890",
        "carrier_hub_id": "ORD"
    },
    "rates": [
        {
            "object_created": "2022-12-09T13:27:26.219Z",
   "object_id": "faef46ec7aa041adb700d288eb75df9d",
            "object_owner": "nataliya_eng@shippo.com",
            "shipment": "f2f1bf3f4a004ce2b609f7c19251b15d",
            "attributes": [
                "CHEAPEST"
            ],
            "amount": "6.10",
            "currency": "USD",
            "amount_local": "8.99",
            "currency_local": "AUD",
            "provider": "APG",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/apg.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/apg.png",
            "servicelevel": {
                "name": "ePacket Plus",
                "token": "epacket_plus",
                "terms": "Only delivery tracking in destination country",
                "extended_token": "epacket_plus",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "2edac0dddcfc4416b2708cc10b2d11e0",
            "test": true,
            "zone": null
        },
        {
            "object_created": "2022-12-09T13:27:26.219Z",
            "object_id": "afd962698779489d9210cc7ed0ea0f4a",
            "object_owner": "nataliya_eng@shippo.com",
            "shipment": "f2f1bf3f4a004ce2b609f7c19251b15d",
            "attributes": [],
            "amount": "9.76",
            "currency": "USD",
            "amount_local": "14.38",
            "currency_local": "AUD",
            "provider": "APG",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/apg.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/apg.png",
            "servicelevel": {
                "name": "eParcel premium",
                "token": "eparcel_premium",
                "terms": "",
                "extended_token": "eparcel_premium",
                "parent_servicelevel": null
                            },
                            "estimated_days": null,
                            "arrives_by": null,
                            "duration_terms": "",
                            "messages": [],
                            "carrier_account": "2edac0dddcfc4416b2708cc10b2d11e0",
                            "test": true,
                            "zone": null
                        }
                    ],
                    "messages": [],
                    "metadata": "Customer ID 123456",
                    "test": true,
                    "order": null
                }

Overview

Get started

AI & agents

Guides

Concepts

HTTP Method

URL

Request Payload

Objects

Address

Parcel

Line Items

Customs Declaration

Extra Details

Response Code

Examples

Request Sample

Response Sample

​HTTP Method

​URL

​Request Payload

​Objects

​ Address

​ Parcel

​ Line Items

​ Customs Declaration

​ Extra Details

​Response Code

​Examples

​Request Sample

​Response Sample

HTTP Method

URL

Request Payload

Objects

Address

Parcel

Line Items

Customs Declaration

Extra Details

Response Code

Examples

Request Sample

Response Sample