Shipments

When using the shiplineitems method, you need to provide the quantity and an identifier for each line item that you want to ship. You can use either the LineitemId or the Product REST Id (channel:language:country:merchant item Id), both of which you can find when you retrieve an order using list.

You must provide these properties for each line item, together with the shipmentInfos field in the request body of the shiplineitems method. The shipmentInfos field consists of the shipmentId, the carrier and the trackingID for each shipment in the order. The field can be used multiple times in a single call because a single line item can be shipped in several packages (and have several tracking IDs) and needs a separate shipmentInfos field for each package.

There are three different scenarios that you can consider, depending on your requirements:

• Multiple Line Items - One Shipment/Tracking Id

• One Line Item - Multiple Shipments/Tracking Ids

• Multiple Line Items - Multiple Shipments/Tracking Ids

Multiple line items in one shipment

If you want to ship several items in a single package, you need to call shiplineitems once and insert a shipmentInfos section in the body of your request and add multiple items, specifying the shipmentId, carrier and trackingId. Take for example, you have an order for one USB stick and one DVD, which you will ship together in a single package as shown below.

The request body for this call should look like this:

{
  "lineItems": [
    {
      "lineItemId": "2IDODSM5LLCZEYE",
      "quantity": 1
    },
    {
      "ProductId": "online:eng:US:df4sg5ds",
      "quantity": 1
    }
  ],
  "shipmentInfos": [
    {
    "shipmentId": "12345",
    "carrier": "FedEx",
    "trackingId": "12222"
    }
  ]
}

One line item in multiple shipments

If you want to ship a large item that is too big to dispatch in one package, for example, a bulky table that you must assemble at home, you can split the item into multiple packages. Call shiplineitems once, but you have to enter one single lineitemId, and multiple shipmentInfos sections, with a shipmentId for each separate package, as in the example below.

The request body for this call should look like this:

{
  "lineItems": [
    {
      "lineItemId": "CYBIDQWXDKCZEYE",
      "quantity": 1
    }
  ],
  "shipmentInfos": [
    {
      "shipmentId": "shipment-1",
      "carrier": "FedEx",
      "trackingId": "22222"
    },
    {
      "shipmentId": "shipment-2",
      "carrier": "FedEx",
      "trackingId": "33333"
    },
    {
      "shipmentId": "shipment-3",
      "carrier": "FedEx",
      "trackingId": "4444"
    }
  ]
}

Multiple line items in multiple shipments

If you want to split up orders and ship multiple line items in multiple shipments, you have to call the shiplineitems method multiple times so that each shipment matches one of the scenarios shown above. This is required because line items cannot be mapped to specific shipmentInfos when you define multiples of each. This makes tracking difficult when you split up line items and send them in packages with other line items as customers will not be notified of deliveries until all items have been marked as delivered. Sending a large article as a single trackable line item provides the best customer experience as there is just one package to track and one notification required.

It is possible that you will encounter a situation which consists of the following:

• one large item being shipped in multiple packages, for example, the table from the example above

• two smaller items which are included in a package with the larger bulky item, for example, the DVD, the USB and part of the table

In this scenario, three separate packages are sent; one package contains two line items (USB and DVD) and part of the third line item (table), while the second and third packages each contain the other two parts of the line item (table) that has been split into three. You have to call shiplineitems twice, using four shipment infos resource entries in total; the first line item for shipping multiple line items in a single package and the second time for shipping one item in multiple packages.

First call - multiple line items in one shipment

In this example, you call shiplineitems the first time to ship multiple items in a single package.

{
  "lineItems": [
    {
      "lineItemId": "TOTZQWXDKCZEYE",
      "quantity": 1
    },
    {
      "lineItemId": "DEIDQWXDKCZEYE",
      "quantity": 1
    }
  ],
  "shipmentInfos": [
    {
    "shipmentId": "Shipment-1",
    "carrier": "FedEx",
    "trackingId": "11111"
    }
  ]
}

Second call - one line item in three shipments

In this example, you call shiplineitems to ship the same line item in multiple packages.

{
  "operationId": "operation-2",
  "lineItems": [
    {
      "lineItemId": "BBIDQWXDKCZEYE",
      "quantity": 1
    }
  ],
  "shipmentInfos": [
    {
      "shipmentId": "shipment-2",
      "carrier": "FedEx",
      "trackingId": "1111"
    },
    {
      "shipmentId": "shipment-3",
      "carrier": "UPS",
      "trackingId": "33333"
    },
    {
      "shipmentId": "shipment-4",
      "carrier": "Hermes",
      "trackingId": "44444"
    }
  ]
}