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

Copy
Copied
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.
Copy
Copied
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

Copy
Copied
curl --location --request POST 'https://api.goshippo.com/carrier_accounts/' \
--header 'Authorization: ShippoToken shippo_live_******' \
--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

Copy
Copied
 {
    "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
                }