Book Shipment

Use this endpoint to book a shipment.

REST Endpoint

POST /restapi/v1/customers/:customerId/shipments

Request Content Type

application/json

Request JSON Example of Domestic Shipment

{
  "carrierCode": "ups",
  "serviceCode": "ups_ground",
  "packageTypeCode": "ups_custom_package",
  "shipmentDate": "2020-04-21",
  "shipmentReference": "abc123",
  "contentDescription": "",
  "sender": {
    "name": "Albert Jones",
    "company": "Jones Co.",
    "address1": "123 Some Street",
    "address2": "#54",
    "city": "Holladay",
    "state": "UT",
    "zip": "84117",
    "country": "US",
    "phone": "8015042351",
    "email": "test@test.com"
  },
  "receiver": {
    "name": "Alice Jensen",
    "company": "",
    "address1": "54 Green St.",
    "address2": "",
    "city": "Salt Lake City",
    "state": "UT",
    "zip": "84106",
    "country": "US",
    "phone": "8013920046"
  },
  "residential": true,
  "signatureOptionCode": "DIRECT",
  "weightUnit": "lb",
  "dimUnit": "in",
  "currency": "USD",
  "customsCurrency": "USD",
  "pieces": [
    {
      "weight": "1.4",
      "length": "5.1",
      "width": "4",
      "height": "2.5",
      "insuranceAmount": "12.15",
      "declaredValue": null,
      "lineItems": [
        {
          "sku": "ABC-123",
          "productName": "Blue Widget",
          "quantity": 2
        }
      ]
    }
  ],
  "billing": {
    "party": "sender",
    "account": "123456",
    "country": "US",
    "zip": "84106"
  },
  "providerAccountId": null
}

Request JSON Example of International Shipment

{
  "carrierCode":"usps",
  "serviceCode":"usps_international_priority",
  "packageTypeCode":"usps_custom_package",
  "shipmentDate":"2019-04-19",
  "shipmentReference":"abc123",
  "sender":{
    "name":"Test Sender",
    "company":"Test Sender",
    "address1":"562 W Pacific Dr",
    "address2":"",
    "city":"American Fork",
    "state":"UT",
    "zip":"84003",
    "country":"US",
    "phone":"8001231234",
    "email": "test@test.com"
  },
  "receiver":{
    "name":"Test Recipient",
    "company":"Test Company",
    "address1":"Pilatusstrasse 1",
    "address2":"",
    "city":"Luzern",
    "state":"LU",
    "zip":"6003",
    "country":"CH",
    "phone":"8001231234",
    "email":"test2@test.com"
  },
  "residential":false,
  "signatureOptionCode":null,
  "contentDescription":"Test contents",
  "contentType": "merchandise", 
  "weightUnit":"lb",
  "dimUnit":"in",
  "currency":"USD",
  "customsCurrency":"USD",
  "pieces":[
    {
      "weight":"1",
      "length":"1",
      "width":"1",
      "height":"1",
      "insuranceAmount":null,
      "declaredValue":null
    }
  ],
  "commercialInvoice":{
    "sendElectronically": true,
    "ftrNumber":null,
    "itnNumber":null,
    "aesNumber":null,
    "termsOfTrade":"CIP",
    "receiverTaxId":"XXX-XX-XXXX",
    "packageMarks":"",
    "consignee":{
      "name":"Test Consignee",
      "company":"Test Consignee Company",
      "address1":"Consignee Street 1",
      "address2":"",
      "city":"Luzern",
      "state":"LU",
      "zip":"6003",
      "country":"CH",
      "phone":"8001231234",
      "email":"consignee@test.com"
    },
    "importerOfRecord":{
      "name":"Test Importer",
      "company":"Test Importer Company",
      "address1":"Importer Street 1",
      "address2":"",
      "city":"Luzern",
      "state":"LU",
      "zip":"6003",
      "country":"CH",
      "phone":"8001231234",
      "email":"importer@test.com"
    },
    "items":[
      {
        "description":"test item description",
        "quantity":1,
        "unitValue":"1.00",
        "weight":"1",
        "htsNumber":"",
        "eccnNumber":"EAR99",
        "countryOfOrigin":"US"
      }
    ]
  },
  "billing":{
    "party":"sender"
  },
  "approvePrepayRecharge":false,
  "scanBasedReturnLabel":false
}

Explanation of Request Fields

Field	Type	Required	Description
carrierCode	string	true	The carrier code
serviceCode	string	true	The service code
packageTypeCode	string	true	The package type code
shipmentDate	date	true	The date of the shipment
shipmentReference	string	false	Shipment reference value (for example, an invoice number)
shipmentReference2	string	false	Shipment reference value (for example, an invoice number)
contentDescription	string	false	Human readable description of content
contentType	string	false	Carrier specific content type
orderNumber	string	false	Invoice number of order
sender.name	string	true	Name of sender
sender.company	string	true	Company name of sender
sender.address1	string	true	Sender street address line 1
sender.address2	string	true	Sender street address line 2
sender.city	string	true	Sender city
sender.state	string	true	Sender state/province (must be two-character code for US and CA)
sender.zip	string or null	true	Sender zip or postal code
sender.country	string	true	ISO two-character country code
sender.phone	string	true	10-digit phone number
sender.email	string	false	Sender email
receiver.name	string	true	Name of receiver
receiver.company	string	true	Company name of receiver
receiver.address1	string	true	Receiver street address line 1
receiver.address2	string	true	Receiver street address line 2
receiver.city	string	true	Receiver city
receiver.state	string	true	Receiver state/province (must be two-character code for US and CA)
receiver.zip	string or null	true	Receiver zip or postal code
receiver.country	string	true	ISO two-character country code
receiver.phone	string	true	10-digit phone number
receiver.email	string	false	Receiver email
returnTo.name	string	false	Name of Return To
returnTo.company	string	false	Company name of Return To
returnTo.address1	string	false	Return To street address line 1
returnTo.address2	string	false	Return To street address line 2
returnTo.city	string	false	Return To city
returnTo.state	string	false	Return To state/province (must be two-character code for US and CA)
returnTo.zip	string or null	false	Return To zip or postal code
returnTo.country	string	false	ISO two-character country code
returnTo.phone	string	false	10-digit phone number
residential	boolean	false	Set to true if the receiver address is residential
signatureOptionCode	string or null	false	Signature option code for shipment. Null for no signature
dangerousGoodsCode	string	false	Dangerous goods code (currently only available for DHL Ecommerce)
uspsExpressAmDelivery	boolean	false	10:30 AM Delivery
saturdayDelivery	boolean	false	Saturday Delivery
weightUnit	string	true	"lb" for pounds, "oz" for ounces, "kg" for kilograms, or "g" for grams
dimUnit	string or null	true	Either "in" for inches or "cm" for centimeters or null if packageType has preset dimensions
currency	string	true	The currency of the provided insuranceAmount, declaredValue, and customsValue (if customsCurrency is not present) fields. (USD, GBP, CAD, EUR)
customsCurrency	string	true	If present, is the currency of the provided customsValue. (USD, GBP, CAD, EUR)
labelImageFormat	string or null	false	Either "PDF", "EPL2" (FedEx only), "ZPL" (Fedex, UPS and USPS only), or "PNG" (DHL eCommerce only)
pieces[n].weight	string	true	Numeric weight as a JSON string
pieces[n].length	string or null	true	Numeric length as a JSON string (set to null if packageType has preset dimensions)
pieces[n].width	string or null	true	Numeric width as a JSON string (set to null if packageType has preset dimensions)
pieces[n].height	string or null	true	Numeric height as a JSON string (set to null if packageType has preset dimensions)
pieces[n].insuranceAmount	decimal or null	true	The value of the piece to be covered by insurance. Must be null for no insurance
pieces[n].declaredValue	decimal or null	true	The declared value of the piece for international shipments. Must be null for domestic shipments
pieces[n].lineItems	array or null	false	Optional line items for this piece. Preserve order and duplicates; use empty SKU if unknown.
pieces[n].lineItems[n].sku	string	true	SKU for this piece line item (may be empty string)
pieces[n].lineItems[n].productName	string	true	Product name for this piece line item
pieces[n].lineItems[n].quantity	integer	true	Quantity for this piece line item
approvePrepayRecharge	boolean	false	Set to true to automatically recharge customer prepay balance if shipment cost exceeds remaining balance
scanBasedReturnLabel	boolean	false	Set to true to create a scan-based return label (USPS only)
commercialInvoice	object or null	false	Pass this if you wish to create a commercial invoice for the shipment
commercialInvoice.sendElectronically	boolean	false	Set to true to electronically submit commerical invoice to DHL, UPS, and FedEx. (Physical commercial invoice may still be required)
commercialInvoice.ftrNumber	string or null	true	Commercial invoice FTR Number (must be null if either itnNumber or aesNumber is present)
commercialInvoice.itnNumber	string or null	true	Commercial invoice ITN Number (must be null if either ftrNumber or aesNumber is present)
commercialInvoice.aesNumber	string or null	true	Commercial invoice AES Number (currently must be null... will be supported in the future)
commercialInvoice.termsOfTrade	string	true	Must be one of CIP, CPT, DAP, DAT, DDP, EXW, or FCA
commercialInvoice.receiverTaxId	string	true	Printed on the commercial invoice
commercialInvoice.senderVatTaxId	string	true	Printed on the commercial invoice
commercialInvoice.senderTaxIdNumberType	string	false	Type of the sender's tax ID number (senderVatTaxId). One of ein (Employer Identification Number), dns (DUNS), or fgn (foreign tax ID). Defaults to ein if omitted. Used for UPS international shipments.
commercialInvoice.dhlTaxIds	array	false	Up to two DHL Express commercial-invoice tax IDs (e.g. an EORI number for EU customs clearance). Only consumed by DHL Express; ignored by other carriers. To send an EORI, add an entry with type set to EOR.
commercialInvoice.dhlTaxIds[n].number	string	true	The tax-id value (for an EORI, the EORI number). Must be non-empty.
commercialInvoice.dhlTaxIds[n].type	string	true	Tax-id type code. Must be one of EOR (EORI), VAT, FTZ, CNP, EIN, or FED
commercialInvoice.dhlTaxIds[n].issuerCountry	string	false	ISO two-character country code of the tax-id issuer
commercialInvoice.packageMarks	string	true	Printed on the commercial invoice
commercialInvoice.consignee	object or null	false	Address information for the consignee on the commercial invoice
commercialInvoice.consignee.name	string	true	Name of consignee
commercialInvoice.consignee.company	string	false	Company name of consignee
commercialInvoice.consignee.address1	string	true	Consignee street address line 1
commercialInvoice.consignee.address2	string	false	Consignee street address line 2
commercialInvoice.consignee.city	string	true	Consignee city
commercialInvoice.consignee.state	string	false	Consignee state/province (must be two-character code for US and CA)
commercialInvoice.consignee.zip	string or null	true	Consignee zip or postal code
commercialInvoice.consignee.country	string	true	ISO two-character country code
commercialInvoice.consignee.phone	string	false	10-digit phone number
commercialInvoice.consignee.email	string	false	Consignee email
commercialInvoice.importerOfRecord	object or null	false	Address information for the importer of record on the commercial invoice
commercialInvoice.importerOfRecord.name	string	true	Name of importer of record
commercialInvoice.importerOfRecord.company	string	false	Company name of importer of record
commercialInvoice.importerOfRecord.address1	string	true	Importer of record street address line 1
commercialInvoice.importerOfRecord.address2	string	false	Importer of record street address line 2
commercialInvoice.importerOfRecord.city	string	true	Importer of record city
commercialInvoice.importerOfRecord.state	string	false	Importer of record state/province (must be two-character code for US and CA)
commercialInvoice.importerOfRecord.zip	string or null	true	Importer of record zip or postal code
commercialInvoice.importerOfRecord.country	string	true	ISO two-character country code
commercialInvoice.importerOfRecord.phone	string	false	10-digit phone number
commercialInvoice.importerOfRecord.email	string	false	Importer of record email
commercialInvoice.items[n].description	string	true	Description of item on commercial invoice
commercialInvoice.items[n].quantity	integer	true	Quantity of item printed on commercial invoice
commercialInvoice.items[n].unitValue	decimal	true	Per-unit value of item on commercial invoice
commercialInvoice.items[n].weight	string	false	Numeric weight as a JSON string of item on commercial invoice
commercialInvoice.items[n].htsNumber	string	true	Harmonized Tariff Schedule number for item on commercial invoice
commercialInvoice.items[n].eccnNumber	string	false	Export Control Classification Number (e.g., "EAR99", "3A001"). Required when shipping from the US to CN, HK, RU, or VE. Must be exactly 5 characters when required.
commercialInvoice.items[n].countryOfOrigin	string	true	ISO two-character country code of origin for item on commercial invoice
billing.party	string	false	Billing party: "sender" for Sender, "receiver" for Receiver, "third_party" for Third Party
billing.account	string or null	false	Billing account number
billing.country	string or null	false	ISO two-character country code
billing.zip	string or null	false	Billing zip or postal code
billing.dutiableParty	object or null	false	Pass this object if you'd like to specify a dutiable party during billing
billing.dutiableParty.dutyPaymentType	string or null	false	Dutiable party: "sender" for Sender, "receiver" for Receiver, "third_party" for Third Party
billing.dutiableParty.dutyPaymentAccountNumber	string or null	false	Required if the dutyPaymentType is a "receiver" or "third_party". This is the account number used to pay the duty charges.
providerAccountId	string or null	false	Provider Account ID which can be retrieved using the List Provider Accounts endpoint
uspsEndorsement	string or null	false	USPS endorsement for the given provider (currently dhlecommerce only)

Response Status Code

201 Created

Response Content Type

application/json

Response JSON Example

{
  "bookNumber": "2317948",
  "trackingNumber": "1ZA3R6625221693812",
  "prepayBalance": "21.53",
  "zone": "2"
}

Explanation of Response Fields

Field	Type	Description
bookNumber	string	Unique ID for this shipment
trackingNumber	string	Carrier specific tracking number for this shipment
prepayBalance	string	The customer's new prepay balance after booking this shipment
zone	string	The zone used to compute shipping cost
pieces	array	Only present for USPS multipiece shipments, contains an array for each piece with string trackingNumber and string shippingCost for that respective piece

Changelog

Date	Notes
2018-04-12	Added returnTo object.
2025-03-24	Added sendElectronically option
2026-04-10	Added commercialInvoice.items[n].eccnNumber field for Export Control Classification Number
2026-06-29	Added commercialInvoice.dhlTaxIds[n].number/type/issuerCountry for sending DHL Express tax IDs, including an EORI number (type = EOR) for EU customs clearance
2026-07-01	Added commercialInvoice.senderTaxIdNumberType (was already supported by the backend but missing from the schema)