v1

latestOpenAPI 3.1.02026-07-1270243932.3 KB

Shipments

Create a new shipment

Creates a new shipment object.

post/shipments

Headers

SHIPPO-API-VERSIONstring

Example:2018-02-08

Optional string used to pick a non-default API version to use. See our <a href="https://docs.goshippo.com/docs/api_concepts/apiversioning/">API version</a> guide.

Request body

metadatastring

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

shipment_datestring

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.

asyncboolean

carrier_accountsstring[]

List of <a href="/shippoapi/public-api/carrier-accounts">Carrier Accounts</a> object_ids used to filter the returned rates. If set, only rates from these carriers will be returned.

Carrier	Constraints
FedEx	Max 30 items

Example request

{
  "extra": {
    "accounts_receivable_customer_account": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "appropriation_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "bill_of_lading_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "COD": {
      "amount": "5.5",
      "currency": "USD",
      "payment_method": "CASH"
    },
    "cod_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "customer_reference": {
      "ref_sort": 1
    },
    "dealer_order_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "dept_number": {
      "ref_sort": 3
    },
    "fda_product_code": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "insurance": {
      "amount": "5.5",
      "currency": "USD"
    },
    "invoice_number": {
      "ref_sort": 2
    },
    "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": {
      "ref_sort": 2
    },
    "production_code": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "purchase_request_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "rma_number": {
      "ref_sort": 1
    },
    "salesperson_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "serial_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "store_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "transaction_reference_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    }
  },
  "metadata": "Customer ID 123456",
  "shipment_date": "2021-03-22T12:00:00Z",
  "address_from": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "validate": true
  },
  "address_return": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "validate": true
  },
  "address_to": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "validate": true
  },
  "customs_declaration": {
    "b13a_filing_option": "FILED_ELECTRONICALLY",
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "contents_explanation": "T-Shirt purchase",
    "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"
      }
    },
    "invoice": "#123123",
    "metadata": "Order ID #123123",
    "address_importer": {
      "name": "Shwan Ippotle",
      "company": "Shippo",
      "street1": "Blumenstraße",
      "street_no": "22",
      "city": "München",
      "state": "CA",
      "zip": "80331",
      "country": "DE",
      "phone": "80331",
      "email": "shippotle@shippo.com",
      "is_residential": true
    },
    "contents_type": "MERCHANDISE",
    "eel_pfc": "NOEEI_30_37_a",
    "incoterm": "DDP",
    "items": [
      {
        "description": "T-Shirt",
        "mass_unit": "lb",
        "metadata": "Order ID \"123454\"",
        "net_weight": "5",
        "quantity": 20,
        "sku_code": "HM-123",
        "hs_code": "0901.21",
        "value_amount": "200",
        "value_currency": "USD"
      }
    ],
    "non_delivery_option": "RETURN",
    "test": true
  },
  "carrier_accounts": [
    "065a4a8c10d24a34ab932163a1b87f52",
    "73f706f4bdb94b54a337563840ce52b0"
  ],
  "parcels": [
    {
      "extra": {
        "COD": {
          "amount": "5.5",
          "currency": "USD",
          "payment_method": "CASH"
        },
        "insurance": {
          "amount": "5.5",
          "content": "Laptop",
          "currency": "USD",
          "provider": "UPS"
        }
      },
      "metadata": "Customer ID 123456",
      "mass_unit": "lb",
      "weight": "1",
      "distance_unit": "in",
      "height": "1",
      "length": "1",
      "width": "1"
    }
  ]
}

Response

Shipment

metadatastring required

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

shipment_datestring

carrier_accountsstring[] 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.

object_createdstring date-time required

Date and time of Shipment creation.

object_idstring required

Unique identifier of the given Shipment object.

object_ownerstring required

Username of the user who created the Shipment object.

object_updatedstring date-time required

Date and time of last Shipment update.

status'ERROR' | 'QUEUED' | 'SUCCESS' | 'WAITING' 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.

testboolean

Indicates whether the object has been created in test mode.

Example response

{
  "extra": {
    "accounts_receivable_customer_account": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "appropriation_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "bill_of_lading_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "COD": {
      "amount": "5.5",
      "currency": "USD",
      "payment_method": "CASH"
    },
    "cod_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "customer_reference": {
      "ref_sort": 1
    },
    "dealer_order_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "dept_number": {
      "ref_sort": 3
    },
    "fda_product_code": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "insurance": {
      "amount": "5.5",
      "currency": "USD"
    },
    "invoice_number": {
      "ref_sort": 2
    },
    "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": {
      "ref_sort": 2
    },
    "production_code": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "purchase_request_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "rma_number": {
      "ref_sort": 1
    },
    "salesperson_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "serial_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "store_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    },
    "transaction_reference_number": {
      "prefix": "ABC",
      "value": "value",
      "ref_sort": 1
    }
  },
  "metadata": "Customer ID 123456",
  "shipment_date": "2021-03-22T12:00:00Z",
  "address_from": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "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": {
      "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"
        }
      ]
    }
  },
  "address_return": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "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": {
      "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"
        }
      ]
    }
  },
  "address_to": {
    "name": "Shwan Ippotle",
    "company": "Shippo",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@shippo.com",
    "is_residential": true,
    "metadata": "Customer ID 123456",
    "is_complete": true,
    "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": {
      "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"
        }
      ]
    }
  },
  "customs_declaration": {
    "b13a_filing_option": "FILED_ELECTRONICALLY",
    "certify": true,
    "certify_signer": "Shawn Ippotle",
    "contents_explanation": "T-Shirt purchase",
    "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"
      }
    },
    "invoice": "#123123",
    "metadata": "Order ID #123123",
    "address_importer": "257ba08436604d2aaf069caafe7acb2a",
    "contents_type": "MERCHANDISE",
    "eel_pfc": "NOEEI_30_37_a",
    "incoterm": "DDP",
    "items": [
      "5087f181d1dc4b14b73fdbf636498886"
    ],
    "non_delivery_option": "RETURN",
    "object_created": "2014-07-17T01:01:08.306Z",
    "object_id": "e2197a54da9d470480f4f8796cc419cb",
    "object_owner": "shippotle@shippo.com",
    "object_updated": "2014-07-17T01:01:08.306Z",
    "test": true
  },
  "messages": [
    {
      "source": "UPS",
      "code": "carrier_timeout",
      "text": "UPS API did not respond. Please try again in a few minutes."
    }
  ],
  "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
  "object_owner": "pp@gmail.com",
  "parcels": [
    {
      "extra": {
        "COD": {
          "amount": "5.5",
          "currency": "USD",
          "payment_method": "CASH"
        },
        "insurance": {
          "amount": "5.5",
          "content": "Laptop",
          "currency": "USD",
          "provider": "UPS"
        }
      },
      "metadata": "Customer ID 123456",
      "mass_unit": "lb",
      "weight": "1",
      "distance_unit": "in",
      "height": "1",
      "length": "1",
      "width": "1",
      "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"
    }
  ],
  "rates": [
    {
      "amount": "5.5",
      "amount_local": "5.5",
      "currency": "USD",
      "currency_local": "USD",
      "arrives_by": "08:30:00",
      "carrier_account": "078870331023437cb917f5187429b093",
      "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."
        }
      ],
      "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
      "object_owner": "pp@gmail.com",
      "provider": "USPS",
      "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
      "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
      "servicelevel": {
        "name": "Priority Mail Express",
        "token": "usps_priority_express",
        "parent_servicelevel": {
          "name": "Priority Mail Express",
          "token": "usps_priority_express"
        }
      },
      "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
      "zone": "1"
    }
  ],
  "status": "QUEUED"
}