The following instructions apply to v2 of the Sendcloud API.
| Entity | Definition |
|---|
| Order | This dataset contains information about an order made in the webshop. |
| Shipment | This dataset contains information about the order and its destination. Shipments can have a parcel linked to them. Note that shipments are visually represented in the Incoming orders view of the Sendcloud platform. This means that on the front end the word “shipment” is not used. When working with our APIs, use shipments, not orders. |
| Parcel | This dataset contains information about a shipment’s delivery. When you work with a parcel, it typically comes with a label that’s connected to the carrier. |
| Label | Shipping labels display the key information for a carrier to transport a package from its start destination (e.g. your warehouse), to its end destination (the customer). Label design may differ for each carrier, but all labels have addresses, names, weights, and tracking barcodes. |
| Field | Definition |
|---|
order_number | The order number imported from your Webshop, ERP, or WMS. It may contain duplicates because the imported number will not necessarily be unique. If you use Pack & Go and have a duplicate of the order_number, keep in mind that scanning the field will result in a ‘The order has already been processed’ error. |
Parcel id | The parcel id is automatically generated by Sendcloud when creating a parcel and is used to identify parcels within the platform. |
shipment_uuid | When you create a shipment, Sendcloud generates the shipment_uuid to identify it within the platform. Every shipment, synced by a webshop integration has a shipment_uuid. This field can be used to link a parcel to a shipment. |
Overview
This setup is useful if you want to have Sendcloud in the checkout of your webshop, while fulfilling orders from a different system, such as an ERP or WMS. It allows using Sendcloud’s plug-and-play webshop integrations, which already have many features implemented.
In this setup, shipments are sent to Sendcloud via a webshop integration and must be fulfilled via the Sendcloud API. You can create labels for shipments already in Sendcloud, and you don’t even have to log into Sendcloud to fulfill orders and print labels. This could be done through a system of your choice, such as an ERP or WMS. This setup also allows you to ship parcels to a service point that the customer has selected in the webshop.
Basic flow
The webshop sends over shipments to Sendcloud. The fulfillment system also has the shipment data and can request labels directly from Sendcloud for a specific order via the custom integration setup. You can request a label when you have a parcel for the order. When you link a parcel to the shipment and request a label, Sendcloud will automatically update the webshop with information on the parcel.
Note that sending the parcel information back to the webshop depends on the webshop’s system. Some webshops might not
have a field for track-and-trace links or carrier statuses as specific as Sendcloud does, for example — a webshop
might only have Open and Shipped statuses, while Sendcloud offers more.
Technical flow
The following sequence diagram breaks down the detailed flow of the setup. The custom integration should cover the steps in the purple box in the middle of the diagram:
Fetch a shipment
To acquire the shipment details of orders sent in by an official integration, make a GET request to the Retrieve a list of shipments endpoint.
In the GET request, specify a query parameter that matches the order_number, and external_order_id (if applicable) or external_shipment_id (if applicable) parameters. These fields are originally inserted by the shop system integration. In the request URL, specify the integration ID. To retrieve the integration ID, use the Retrieve a list of integrations endpoint.
Note that If you have multiple webshop integrations connected to your Sendcloud account, it should be clear which order number is attached to which integration ID.
Fetch a parcel
In some cases, the webshop integration might be directly creating parcels in Sendcloud rather than shipments, e.g. a custom webshop integration. In this case, make a GET request to the Retrieve parcels endpoint.
In the GET request, specify a query parameter that matches the order_number field.
Create a parcel and request a label
When the order details have been acquired, you can create the parcel and request the label. To do this, use the Create a parcel or parcels endpoint.
Note that when creating the parcel, you can redefine most of the fields. The parcel fields do not need to be equal to the original shipment. However, some fields do need to be the same for the described setup to work as intended:
| Field | Definition |
|---|
shipment_uuid | The webshop feedback uses this field to link the parcel with the shipment. |
service_point_id | The service point ID of the shipment. |
to_post_number | The Post number field of shipment. |
shipping_method_checkout_name | This is a text field used for matching in shipping rules. It usually has the webshop checkout’s shipping method name, but can be changed if the name isn’t clear enough for setting a rule. |
Fetch the label
The Create a parcel or parcels endpoint response includes various ways to fetch the label:
- The
label field in the response:
normal_printer provides an A4 document with the label on it. The default format is PDF. Note that the start_from parameter in each URL determines where the label will be printed on the page: top left, top right, bottom left and bottom right. See the Retrieve a PDF label endpoint.label_printer provides an A6 label document for label printers. See the Retrieve a PDF label for a specific label printer endpoint.
- The
documents field contains a label URL, plus (if applicable) additional documents for international shipments outside of the EU. See the Retrieve parcel documents endpoint.
- Note that it is possible to get the label in different formats including ZPL using the API v3 Retrieve a parcel document endpoint.
To download the label, redirect to that link and provide the same API credentials used to request the label. The link cannot be opened if these credentials are not provided.
