Shipment (Delivery Estimate-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 prior Customer Delivery Estimates.

This is stage 3 in the Product View - Order - Shipment - Deliver sequence for Estimate-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 included with information about the Fulfillment Center.

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 deliveryEstimateId and quantity, you can simply POST to the order ship API's endpoint - /deliveryexperience/order/{customerOrderId}/ship - to create a shipment with the exact contents of the original order.

  • The more complex case is when you combine items from multiple orders for a given Customer and ship them together. For this 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

Shipment API

This means creating a shipment from existing order contents. This example shows the cURL request:

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

This example shows the response:

{
  "carrierName": "ups",
  "carrierTrackingId": "1ZHHDHKAHB01271929",
  "customerCountryCode":"US",
  "customerPostalCode":"98101",
  "orderedDateTime": "2020-03-27T22:14+0000",
  "referenceIdentifier": "yourCustomIdentifier",
  "orderItemQuantities": [
    { "productId": "9780345028853",
      "deliveryEstimateId": "1d02bca8-2008-4f79-9203-48acaf3cad54",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "partnerOrderId": "POID-12345",
      "quantity": 1
    },
    {
      "productId": "9780374533557",
      "deliveryEstimateId": "a6aae036-c7c2-40d7-b15d-f50c7d7e7950",
      "shipiumOrderId": "4dc43fff-c3af-4d7b-8a18-e01f2b4cb312",
      "partnerOrderId": "POID-12345",
      "quantity": 1
    }
  ],
  "shipiumShipmentId": "6b77f2d3-c292-4e28-9891-61daff1e5686",
  "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 example cURL request uses the 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", "customerCountryCode":"US", "customerPostalCode":"98101", "orderItemQuantities": [{"productId": "9780345028853", "deliveryEstimateId": "1d02bca8-2008-4f79-9203-48acaf3cad54", "quantity": 1}, {"productId": "9780374533557", "deliveryEstimateId": "a6aae036-c7c2-40d7-b15d-f50c7d7e7950", "quantity": 1}], "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"}, "partnerShipmentId": "88637117-f0c5-45b8-8c11-c75dfa22a4cc"}'

This example shows the response:

{
  "carrierName": "ups",
  "carrierTrackingId": "1ZHHDHKAHB01271929",
  "customerCountryCode":"US",
  "customerPostalCode":"98101",
  "orderedDateTime": "2020-03-27T22:14+0000",
  "orderItemQuantities": [
    {
      "productId": "9780345028853", 
      "deliveryEstimateId": "1d02bca8-2008-4f79-9203-48acaf3cad54", 
      "quantity": 1
    }, 
    {
      "productId": "9780374533557", 
      "deliveryEstimateId": "a6aae036-c7c2-40d7-b15d-f50c7d7e7950", 
      "quantity": 1
    }
  ], 
  "shipiumShipmentId": "6b77f2d3-c292-4e28-9891-61daff1e5686",
  "partnerShipmentId": "88637117-f0c5-45b8-8c11-c75dfa22a4cc",
  "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 Read API

This example cURL request shows a Shipment Read using the Partner Shipment ID (PSID):

curl --request GET \
  --url <<api_url>>/api/v1/deliveryexperience/shipment/PSID-12345 \
  --header 'accept: application/json' \
  --header $AUTHSTRING

The response to this is the same as the response shown above for Shipment Create API.

📘

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