Skip to main content
POST
/
shipments
cURL
curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d $'{
      "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@shippo.com"
      },
      "address_from": {
          "name": "Mrs Hippo",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "mrshippo@shippo.com"
      },
      "parcels": [{
          "length": "10",
          "width": "15",
          "height": "10",
          "distance_unit": "in",
          "weight": "1",
          "mass_unit": "lb"
      }],
      "async": false
  }'
{
  "metadata": "Customer ID 123456",
  "address_from": {
    "country": "US",
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "street2": "<string>",
    "street3": "",
    "street_no": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "latitude": 123,
    "longitude": 123,
    "object_created": "2014-07-09T02:19:13.174Z",
    "object_id": "d799c2679e644279b59fe661ac8fa488",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2014-07-09T02:19:13.174Z",
    "validation_results": {
      "is_valid": false,
      "messages": [
        {
          "code": "Unknown Street",
          "source": "Shippo Address Validator",
          "text": "City, State and ZIP Code are valid, but street address is not a match.",
          "type": "address_warning"
        }
      ]
    },
    "test": false
  },
  "address_to": {
    "country": "US",
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "street2": "<string>",
    "street3": "",
    "street_no": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "latitude": 123,
    "longitude": 123,
    "object_created": "2014-07-09T02:19:13.174Z",
    "object_id": "d799c2679e644279b59fe661ac8fa488",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2014-07-09T02:19:13.174Z",
    "validation_results": {
      "is_valid": false,
      "messages": [
        {
          "code": "Unknown Street",
          "source": "Shippo Address Validator",
          "text": "City, State and ZIP Code are valid, but street address is not a match.",
          "type": "address_warning"
        }
      ]
    },
    "test": false
  },
  "carrier_accounts": [
    "<string>"
  ],
  "messages": [
    {
      "source": "UPS",
      "code": "carrier_timeout",
      "text": "UPS API did not respond. Please try again in a few minutes."
    }
  ],
  "object_created": "2023-11-07T05:31:56Z",
  "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  "object_owner": "pp@gmail.com",
  "object_updated": "2023-11-07T05:31:56Z",
  "parcels": [
    {
      "mass_unit": "lb",
      "weight": "1",
      "distance_unit": "in",
      "height": "1",
      "length": "1",
      "width": "1",
      "extra": {
        "COD": {
          "amount": "5.5",
          "currency": "USD",
          "payment_method": "CASH"
        },
        "insurance": {
          "amount": "5.5",
          "content": "Laptop",
          "currency": "USD",
          "provider": "UPS"
        },
        "reference_1": "<string>",
        "reference_2": "<string>"
      },
      "metadata": "Customer ID 123456",
      "object_created": "2014-07-09T02:19:13.174Z",
      "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
      "object_owner": "shippotle@shippo.com",
      "object_state": "VALID",
      "object_updated": "2014-07-09T02:19:13.174Z",
      "template": "FedEx_Box_10kg",
      "test": true
    }
  ],
  "rates": [
    {
      "amount": "5.5",
      "amount_local": "5.5",
      "currency": "USD",
      "currency_local": "USD",
      "attributes": [
        "BESTVALUE"
      ],
      "carrier_account": "078870331023437cb917f5187429b093",
      "object_created": "2023-11-07T05:31:56Z",
      "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
      "object_owner": "pp@gmail.com",
      "provider": "USPS",
      "servicelevel": {
        "name": "Priority Mail Express",
        "terms": "<string>",
        "token": "usps_priority_express",
        "extended_token": "<string>",
        "parent_servicelevel": {
          "name": "Priority Mail Express",
          "terms": "<string>",
          "token": "usps_priority_express",
          "extended_token": "<string>"
        }
      },
      "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
      "arrives_by": "08:30:00",
      "duration_terms": "Delivery in 1 to 3 business days",
      "estimated_days": 2,
      "included_insurance_price": "1.05",
      "messages": [
        {
          "source": "UPS",
          "code": "carrier_timeout",
          "text": "UPS API did not respond. Please try again in a few minutes."
        }
      ],
      "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
      "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
      "test": true,
      "zone": "1"
    }
  ],
  "status": "QUEUED",
  "extra": {
    "accounts_receivable_customer_account": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "alcohol": {
      "contains_alcohol": true,
      "recipient_type": "licensee"
    },
    "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
    "appropriation_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "authority_to_leave": true,
    "bill_of_lading_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "billing": {
      "account": "<string>",
      "country": "<string>",
      "participation_code": "<string>",
      "type": "SENDER",
      "zip": "<string>"
    },
    "bypass_address_validation": true,
    "carbon_neutral": true,
    "carrier_hub_id": "<string>",
    "carrier_hub_travel_time": 123,
    "COD": {
      "amount": "5.5",
      "currency": "USD",
      "payment_method": "CASH"
    },
    "cod_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "container_type": "<string>",
    "critical_pull_time": "<string>",
    "customer_branch": "<string>",
    "customer_reference": {
      "prefix": "<string>",
      "value": "<string>",
      "ref_sort": 1
    },
    "dangerous_goods": {
      "contains": true,
      "biological_material": {
        "contains": true
      },
      "lithium_batteries": {
        "contains": true
      }
    },
    "dangerous_goods_code": "01",
    "dealer_order_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "delivery_instructions": "<string>",
    "dept_number": {
      "prefix": "<string>",
      "value": "<string>",
      "ref_sort": 3
    },
    "dry_ice": {
      "contains_dry_ice": true,
      "weight": "<string>"
    },
    "fda_product_code": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "fulfillment_center": "<string>",
    "insurance": {
      "amount": "5.5",
      "content": "<string>",
      "currency": "USD",
      "provider": "FEDEX"
    },
    "invoice_number": {
      "prefix": "<string>",
      "value": "<string>",
      "ref_sort": 2
    },
    "is_return": true,
    "lasership_attrs": [
      "TwoPersonDelivery"
    ],
    "lasership_declared_value": "<string>",
    "manifest_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "model_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "part_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "po_number": {
      "prefix": "<string>",
      "value": "<string>",
      "ref_sort": 2
    },
    "preferred_delivery_timeframe": "10001200",
    "premium": true,
    "production_code": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "purchase_request_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "qr_code_requested": true,
    "reference_1": "<string>",
    "reference_2": "<string>",
    "request_retail_rates": true,
    "return_service_type": "PRINT_AND_MAIL",
    "rma_number": {
      "prefix": "<string>",
      "value": "<string>",
      "ref_sort": 1
    },
    "saturday_delivery": true,
    "salesperson_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "serial_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "signature_confirmation": "STANDARD",
    "store_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "transaction_reference_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "usmca_eligible": true
  },
  "shipment_date": "2021-03-22T12:00:00Z",
  "address_return": {
    "country": "US",
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "street2": "<string>",
    "street3": "",
    "street_no": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "latitude": 123,
    "longitude": 123,
    "object_created": "2014-07-09T02:19:13.174Z",
    "object_id": "d799c2679e644279b59fe661ac8fa488",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2014-07-09T02:19:13.174Z",
    "validation_results": {
      "is_valid": false,
      "messages": [
        {
          "code": "Unknown Street",
          "source": "Shippo Address Validator",
          "text": "City, State and ZIP Code are valid, but street address is not a match.",
          "type": "address_warning"
        }
      ]
    },
    "test": false
  },
  "customs_declaration": {
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "contents_type": "MERCHANDISE",
    "items": [
      "5087f181d1dc4b14b73fdbf636498886"
    ],
    "non_delivery_option": "RETURN",
    "aes_itn": "<string>",
    "b13a_filing_option": "FILED_ELECTRONICALLY",
    "b13a_number": "<string>",
    "certificate": "<string>",
    "commercial_invoice": true,
    "contents_explanation": "T-Shirt purchase",
    "disclaimer": "<string>",
    "duties_payor": {
      "account": "2323434543",
      "type": "THIRD_PARTY",
      "address": {
        "name": "Patrick Kavanagh",
        "zip": "80331",
        "country": "DE"
      }
    },
    "exporter_identification": {
      "eori_number": "PL123456790ABCDE",
      "tax_id": {
        "number": "123456789",
        "type": "EIN"
      }
    },
    "exporter_reference": "<string>",
    "importer_reference": "<string>",
    "is_vat_collected": true,
    "invoice": "#123123",
    "license": "<string>",
    "metadata": "Order ID #123123",
    "notes": "<string>",
    "address_importer": "257ba08436604d2aaf069caafe7acb2a",
    "eel_pfc": "NOEEI_30_37_a",
    "incoterm": "DDP",
    "invoiced_charges": {
      "currency": "<string>",
      "total_shipping": "<string>",
      "total_taxes": "<string>",
      "total_duties": "<string>",
      "other_fees": "<string>"
    },
    "object_created": "2014-07-17T01:01:08.306Z",
    "object_id": "e2197a54da9d470480f4f8796cc419cb",
    "object_owner": "shippotle@shippo.com",
    "object_state": "VALID",
    "object_updated": "2014-07-17T01:01:08.306Z",
    "test": true
  },
  "test": true
}

Authorizations

​
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required

API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123

Headers

​
SHIPPO-API-VERSION
string
default:2018-02-08

Optional string used to pick a non-default API version to use. See our API version guide.

Example:

"2018-02-08"

Body

application/json

Shipment details and contact info.

​
address_from
required

Address represents the address as retrieved from the database

​
address_to
required

Address represents the address as retrieved from the database

​
parcels
object · object · string[]
required

List of parcels to be shipped.

Carrier-Specific Constraints:

CarrierConstraints
FedExMax 30 items
​
extra
Shipment Extra · object

An object holding optional extra services to be requested.

​
metadata
string

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Maximum string length: 100
Example:

"Customer ID 123456"

​
shipment_date
string

Date the shipment will be tendered to the carrier. Must be in the format 2014-01-18T00:35:03.463Z. Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.

Example:

"2021-03-22T12:00:00Z"

​
address_return

Address represents the address as retrieved from the database

​
customs_declaration
​
async
boolean
​
carrier_accounts
string[]

List of Carrier Accounts object_ids used to filter the returned rates. If set, only rates from these carriers will be returned.

Example:
[
  "065a4a8c10d24a34ab932163a1b87f52",
  "73f706f4bdb94b54a337563840ce52b0"
]

Response

Shipment

Shipment represents the parcel as retrieved from the database

​
metadata
string
required

A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

Maximum string length: 100
Example:

"Customer ID 123456"

​
address_from
object
required

Address object of the sender / seller. Will be returned expanded by default.

​
address_to
object
required

Address object of the recipient / buyer. Will be returned expanded by default.

​
carrier_accounts
string[]
required

An array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. 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.

​
messages
object[]
required
​
object_created
string<date-time>
required

Date and time of Shipment creation.

​
object_id
string
required

Unique identifier of the given Shipment object.

Example:

"adcfdddf8ec64b84ad22772bce3ea37a"

​
object_owner
string
required

Username of the user who created the Shipment object.

Example:

"pp@gmail.com"

​
object_updated
string<date-time>
required

Date and time of last Shipment update.

​
parcels
object[]
required

List of Parcel objects to be shipped.

​
rates
object[]
required

An array with all available rates. If async has been 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.

​
status
enum<string>
required

Waiting shipments have been successfully submitted but not yet been processed. Queued shipments are currently being processed. Success shipments have been processed successfully, meaning that rate generation has concluded. Error does not occur currently and is reserved for future use.

Available options:
ERROR,
QUEUED,
SUCCESS,
WAITING
Example:

"QUEUED"

​
extra
Shipment Extra · object

An object holding optional extra services to be requested.

​
shipment_date
string

Date the shipment will be tendered to the carrier. Must be in the format 2014-01-18T00:35:03.463Z. Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.

Example:

"2021-03-22T12:00:00Z"

​
address_return
object

ID of the Address object where the shipment will be sent back to if it is not delivered (Only available for UPS, USPS, and Fedex shipments).
If this field is not set, your shipments will be returned to the address_from.

​
customs_declaration
Customs Declaration · object
​
test
boolean

Indicates whether the object has been created in test mode.