Shipment (Order-Based)

Suggest Edits

Overview

Use the Shipment API - /deliveryexperience/shipment - to report when a Partner has shipped a package containing one or more items, referencing one or more previous order items.

This is stage 2 in the Order - Shipment - Deliver sequence for Order-Based Delivery.

Since this involves a physical package that we want to be able to track, the carrier used to ship the product and the carrier ID are also included along with information about the shipping warehouse.

Note: For a list of CarrierID and Carrier Service Method Id values, see List of canonical carrierId and carrierServiceMethodId values.

There are two ways to create a new shipment entry:

  • The most common ecommerce use case is to ship out exactly the set of items that your Customer purchased in their order. Instead of listing out the set of items by their productIds and quantities, you can simply POST to the order API's ship endpoint - /deliveryexperience/order/{customerOrderId}/ship - to create a shipment with the exact contents of the original order.

  • For the more complex case in which you are combining items from multiple orders for a given Customer and shipping them together, you can specify the contents of the shipment more precisely using the shipment API's POST endpoint, /deliveryexperience/shipment. This allows you to define a shipment that is composed of the contents of one or more orders, or portions of an order if you are shipping out a portion of an order.

API call and response examples are shown below.

📘

Authentication for API calls

In the cURL examples on this page, the environment variable AUTHSTRING is used to handle authorization. The recipe below shows how to set it correctly for both API Key and OAuth users.

🔐
Authenticating for Curl
Open Recipe

Order Ship API

This is the first use case described above.

This example cURL request creates a shipment from existing order contents:

curl --request POST \
  --url <<api_url>>/api/v1/deliveryexperience/order/POID-12345/shipment \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"carrierName": "ups", "carrierTrackingId": "1ZHHDHKAHB01271929", "shippedDateTime": "2020-03-29T22:59+0000", "shipFromAddress":{"addressType": "commercial","city": "Albuquerque","company": "ACME","countryCode": "US","name": "L. Merfudd","postalCode": "87121","state": "NM","street1": "123 Main St.","street2": "Suite 42"}}'

This example shows the response:

{
  "carrierName": "ups",
  "carrierTrackingId": "1ZHHDHKAHB01271929",
  "customerCountryCode":"US",
  "customerPostalCode":"98101",
  "orderedDateTime": "2020-03-27T22:14+0000",
  "orderItemQuantities": [
    { "productId": "9780345028853",
      "partnerOrderId": "POID-12345",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "quantity": 1
    },
    { "productId": "9780374533557",
      "partnerOrderId": "POID-12345",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "quantity": 1
    }
  ],
  "shipiumShipmentId": "6b77f2d3-c292-4e28-9891-61daff1e5686",
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shippedDateTime": "2020-03-29T22:59+0000",
  "shipFromAddress": {
      "addressType": "commercial",
      "city": "Albuquerque",
      "company": "ACME",
      "countryCode": "US",
      "name": "L. Merfudd",
      "postalCode": "87121",
      "state": "NM",
      "street1": "123 Main St.",
      "street2": "Suite 42"
  }
}

Shipment Create API

This is the second use case described above.

This example cURL request uses a customer partnerShipmentId:

curl --request POST \
  --url <<api_url>>/api/v1/deliveryexperience/shipment \
  --header 'accept: application/json' \
  --header $AUTHSTRING \
  --header 'content-type: application/json' \
  --data '{"carrierName": "ups", "carrierTrackingId": "1ZHHDHKAHB01271929", "partnerShipmentId": "88637117-f0c5-45b8-8c11-c75dfa22a4cc", "shipOption": "Standard", "shippedDateTime": "2020-03-29T22:59+0000", "shipFromAddress":{"addressType": "commercial","city": "Albuquerque","company": "ACME","countryCode": "US","name": "L. Merfudd","postalCode": "87121","state": "NM","street1": "123 Main St.","street2": "Suite 42"}, "orderItemQuantities": [{ "productId": "9780345028853", "partnerOrderId": "POID-12345", "quantity": 1}, {"productId": "9780374533557", "partnerOrderId": "POID-67890", "quantity": 1}]}'

This example shows the response:

{
  "carrierName": "ups",
  "carrierTrackingId": "1ZHHDHKAHB01271929",
  "customerCountryCode":"US",
  "customerPostalCode":"98101",
  "orderedDateTime": "2020-03-27T22:14+0000",
  "orderItemQuantities": [
    {
      "productId": "9780345028853",
      "partnerOrderId": "POID-12345",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "quantity": 1
    },
    {
      "productId": "9780374533557",
      "partnerOrderId": "POID-67890",
      "shipiumOrderId": "f018a494-278b-49cb-a736-ef07ff19af10",
      "quantity": 1
    }
  ],
  "partnerShipmentId": "88637117-f0c5-45b8-8c11-c75dfa22a4cc",
  "shipiumShipmentId": "6b77f2d3-c292-4e28-9891-61daff1e5686",
  "shipOption": "Standard",
  "referenceIdentifier": "yourCustomIdentifier",
  "shippedDateTime": "2020-03-29T22:59+0000",
  "shipFromAddress": {
      "addressType": "commercial",
      "city": "Albuquerque",
      "company": "ACME",
      "countryCode": "US",
      "name": "L. Merfudd",
      "postalCode": "87121",
      "state": "NM",
      "street1": "123 Main St.",
      "street2": "Suite 42"
  }
}

Handling special cases

There are several special cases:

  • Special processing and accessorial options - several optional special processing elements can be included as part of the shipmentParameters element. You can find more details about them in Shipment Special Processing Properties.

  • Ship options - you may want to specify a particular class of shipment, such as NextDay, TwoDay, etc. You can do this by specifying a shipOption value. See Shipment Ship Option Overview for more details.

  • Hazardous materials or Limited Quantity/ORMD - where you have one or more items requiring either a Limited Quantity or hazardous materials designation, you will need to specify several additional details for the shipment. You can find the details for handling hazardous materials here.

Shipment Read API

This example cURL request shows Shipment Read using the Partner Shipment ID:

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/88637117-f0c5-45b8-8c11-c75dfa22a4cc \
  --header 'accept: application/json' \
  --header $AUTHSTRING \

The response to this is the same as the response in the shipment creation example above.

📘

More information on the API responses

As with all Shipium API responses, this API follows the API Response Codes standards unless otherwise specified.

Updated 6 months ago