Merchant API: shipments

About this article

This article describes the operations you can perform on shipments via the Merchant API.

Table of contents

Introduction

Available API endpoints

• Create a shipment
• Update a shipment
• Shipping labels
• Overview of shipments

Introduction

You can easily notify your connected channels that your shipment has been sent via the Merchant API. Additionally, you can notify those channels when your shipment has been delivered via a delivery state update, if you have directly delivered the shipment to the buyer. 

The Merchant API also enables you to retrieve available shipping labels for your connected channels as well as filter through a full overview of your shipments. 

Available API endpoints

Create a shipment

Creating a shipment is mandatory to complete the order fulfillment.

• Create a shipment: POST /v2/shipments - either create a finalized shipment including tracking information and carrier method, or draft a shipment without tracking information and update later. 
  • Generally, channels will recognize an order as Shipped if you send the following fields in the request body:
    • Method - the shipping method (i.e.: the name of the carrier fulfilling the order)
    • TrackTraceNo - the tracking number or tracking code. Maximum 50 characters.
  • To find out if the channel accepts partial shipments, check the ChannelOrderSupport field in the response body when you retrieve the order via API, as not all channels support partial shipments.

Create a shipment and update tracking information later

1. Create a shipment via POST /v2/shipments. Make sure the shipment contains the Merchant shipment number, the Merchant order number, and at least one order line. Do not include a placeholder method or tracking code; leave them null. If you do submit data in those fields (even if they are placeholders), the status of the shipment changes to Closed instead of Pending – and ChannelEngine tries to export the shipment to the marketplace. This almost certainly leads to errors on the marketplace, as it considers the tracking information invalid.
2. Once the tracking information becomes available in your system, you can update the shipment via PUT v2/shipments/{merchantShipmentNo}. This call must contain the Method (i.e.: the carrier) and the TrackTraceNo. 
   • The TrackTraceUrl can be left empty, as most marketplaces generate their own link – which is also why the correct carrier and tracking code are important.
   • If you manually fill out the TrackTraceUrl, limit the URL to 250 characters.
3. It is sometimes necessary to use carrier mapping to successfully export the shipment. Bear in mind that your output (i.e.: the Method provided in the shipment) is the input for the carrier mapping. These values must match exactly.

Create a shipment and add a tracking code right away

1. Create a shipment via POST /v2/shipments. Make sure it contains the MerchantShipmentNo, the MerchantOrderNo, at least one order line, the Method, and the TrackTraceNo. Also, there must be no empty or null values, and no placeholders.
2. It is sometimes necessary to use carrier mapping to successfully export the shipment. Bear in mind that your output (i.e.: the Method provided in the shipment), is the input for the carrier mapping. These must match exactly.

Update a shipment

Update a shipment with tracking and return codes

Update any of your tracking and return methods and codes on the shipment after you create the shipment. 

• Update a shipment: PUT /v2/shipments/{merchantShipmentNo} 
  • Every time you send a request using this endpoint, the shipment details are overwritten, a.k.a. "purge and replace".
  • Consult the specific marketplace guide to find out which codes the marketplace requires, if any. 

Update a shipment with the delivery state

• Mark the shipment as delivered: PUT /v2/shipments/{merchantShipmentNo}/delivery-state

  • Status - supported values are ‘Delivered’ and ‘Undelivered’.

  • DeliveredAt - (optional) enter the delivery date and time using the ISO 8601 format yyyy-mm-ddThh:mm:ssZ. The “Z” at the end of the syntax indicates that the time is given in the UTC time zone.
  • Send the delivery state for merchant-fulfilled shipments. 

How to send the delivery state

To send your delivery state to a given channel:

1. If the channel has a Carrier mappings step, enable the Export delivery status toggle for the carrier(s) that you use.
2. If the channel does not have a Carrier mappings step, continue with Step 3.
3. Create your shipments, naming your carrier in the Shipment method.
4. Receive confirmation that the shipment has been delivered.*
5. If the marketplace requires a proof of delivery document, upload the document via the Merchant API or the ChannelEngine web interface. For guidance, check out the next section on proof of delivery or the article ChannelEngine: shipments.
6. Update your shipment with PUT /v2/shipments/{merchantShipmentNo}/delivery-state
   • In the Status field, enter ‘Delivered’ if the shipment was received by the buyer.
   • Or enter ‘Undelivered’ if the shipment was not received by the buyer.

*Make sure that you adhere to your marketplace’s direct delivery policy; some marketplaces require a Proof of Delivery document to accept the shipment’s Delivered state.

Update a shipment with proof of delivery 

• Upload a proof of delivery: POST /v2/shipments/{merchantShipmentNo}/proof-of-delivery
  • document - the URL of your proof of delivery (PoD) document, in PDF format.
  • documentNumber - the unique number of the PoD document.
  • While you can upload a PoD document on any shipment, ChannelEngine exports PoD documents only to those channels that accept them. Consult the specific marketplace guide to find out if your PoD document is accepted by your marketplace. 

Shipping labels

• Request a shipping label from the channel 
  1. Retrieve available carriers POST /v2/carriers/{merchantOrderNo} 
  2. Create the shipment with the chosen carrier POST /v2/shipments
• Download a shipping label: GET /v2/orders/{merchantShipmentNo}/shippinglabel or GET /v2/orders/documents - download a shipping label after it has been requested.
• Retrieve the Air Waybill (AWB) number: GET /v2/orders/{merchantShipmentNo}/airwaybillno - if ChannelEngine generates the AWB number for you (as is the case for certain marketplaces), use this as your tracking code.
• Not all marketplaces make shipping labels available to sellers via API or otherwise. Consult the specific marketplace guide to find out if you should retrieve a shipping label from the marketplace or generate an AWB number.

For more guidance on managing shipping labels, check out ChannelEngine: shipping labels (last-mile delivery).

Overview of shipments

• Filter the full overview of your shipments: GET /v2/shipment 
  • Retrieve a paginated list of shipments and filter by specific shipments using merchantShipmentNos or channelShipmentNos.
  • Filter shipments by their fulfillment type. 
  • Narrow the results through date ranges using fromDeliveredAt and toDeliveredAt.

FAQs

Why is my shipment not processed correctly on the marketplace? 
The main reason for this is that the provided shipment information is missing or incorrect. Review the instructions in the section Create a shipment above.

Does the marketplace accept partial shipments?
Make sure to check the ChannelOrderSupport field in the response body of the retrieve orders API call, as not all marketplaces support partial shipments.

Channel order support assumes one of the following values:

• NONE - the channel does not support any orders or order follow-up actions. E.g.: Beslist does not support automated shipments or returns; therefore, it is not possible to perform any partial order actions.
• NO_SPLIT/ORDERS - the channel supports orders and follow-up actions, but these cannot be split. If an order has two order lines, both must be included in a single shipment.
• SPLIT_ORDERS - the channel supports orders and follow-up actions, but they can only be split into individual order lines. An order containing two order lines, each for one product, can be shipped in two shipments, with each shipment containing one product. However, an order line cannot be split into separate shipments. E.g.: if a buyer buys a quantity of three of the same item, all three items must be shipped at once/canceled at once.
• SPLIT_ORDER_LINES - the channel supports orders and follow-up actions, and their order lines can be split into separate shipments or further follow-up actions. E.g.: if a buyer buys a quantity of three of the same item, it is possible to ship two of the order quantities and cancel one of the quantities.

For more details on retreiving the order support level via the orders endpoint, check out Merchant API: orders.