Fulfill orders
These guidelines describe how an order, synced by a webshop integration to Sendcloud, can be fulfilled via a custom integration. Find more information about the endpoints in the API documentation.
The guideline uses the following terms of Entitles and ID fields:
| 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, for example — 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. |
| ID 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 ID 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 API. You can create labels for shipments already in Sendcloud, 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.
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 shipment
To acquire the shipment details of orders sent in by an official integration, make a GET request to the Retrieving shipments from an integration 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 List of integrations.
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.
Example request
GET
https://panel.sendcloud.sc/api/v2/integrations/45796/shipments?order_number=132232
Example response
1{
2 "next": null,
3 "previous": null,
4 "results": [
5 {
6 "address": "Fischerinsel",
7 "address_2": "",
8 "house_number": "3",
9 "allowed_shipping_methods": [
10 359,
11 1315,
12 8
13 ],
14 "barcode": "PS0000000095224132",
15 "city": "Berlin",
16 "company_name": "company name",
17 "country": "DE",
18 "created_at": "2021-07-16T13:26:11.824853Z",
19 "currency": "EUR",
20 "customs_invoice_nr": "",
21 "customs_shipment_type": null,
22 "email": "test@test.nl",
23 "external_order_id": "167257292",
24 "external_shipment_id": "161523922",
25 "integration": 45796,
26 "name": "John Doe",
27 "order_number": "132232",
28 "order_status": {
29 "id": "processing_awaiting_shipment",
30 "message": "Processing awaiting shipment"
31 },
32 "parcel_items": [
33 {
34 "description": "green bag",
35 "quantity": 1,
36 "weight": "1.000",
37 "value": "110.00",
38 "hs_code": "111111",
39 "origin_country": "NL",
40 "product_id": "3837374",
41 "properties": {
42 "color": "green",
43 "variant": "B"
44 },
45 "sku": "AA6",
46 }
47 ],
48 "payment_status": {
49 "id": "paid",
50 "message": "paid"
51 },
52 "postal_code": "10179",
53 "sender_address": 151250,
54 "shipment_uuid": "90a5bbbf-8e14-46f3-ad7e-195f21558f0f",
55 "shipping_method": 8,
56 "shipping_method_checkout_name": "ship with x",
57 "telephone": "+3161234567",
58 "to_post_number": 111222,
59 "to_service_point": 10608493,
60 "to_state": null,
61 "updated_at": "2021-07-16T13:26:11.824862Z",
62 "weight": "1.000"
63 }
64 ]
65}
Fetch parcel
In some cases, the webshop integration might be directly creating parcels in Sendcloud rather than shipments, for example — custom webshop integration. In this case, make a GET request to the Retrieve parcels Retrieve parcels endpoint.
In the GET request, specify a query parameter that matches the order_number field.
Example request
GET
https://panel.sendcloud.sc/api/v2/parcels?order_number=9966331
Example response
1{
2 "next": null,
3 "previous": null,
4 "parcels": [
5 {
6 "id": 119172953,
7 "address": "Fischerinsel 3",
8 "address_2": "",
9 "address_divided": {
10 "street": "Fischerinsel",
11 "house_number": "3"
12 },
13 "city": "Berlin",
14 "company_name": "company name",
15 "country": {
16 "iso_2": "DE",
17 "iso_3": "DEU",
18 "name": "Germany"
19 },
20 "data": {},
21 "date_created": "16-07-2021 13:04:04",
22 "date_announced": null,
23 "date_updated": "16-07-2021 13:04:04",
24 "email": "test@test.nl",
25 "name": "John Doe",
26 "postal_code": "10179",
27 "reference": "0",
28 "shipment": {
29 "id": 8,
30 "name": "Unstamped letter"
31 },
32 "status": {
33 "id": 999,
34 "message": "No label"
35 },
36 "to_service_point": 10608493,
37 "telephone": "",
38 "tracking_number": "",
39 "weight": "1.000",
40 "label": {},
41 "customs_declaration": {},
42 "order_number": "9966331",
43 "insured_value": 0,
44 "total_insured_value": 0,
45 "to_state": null,
46 "customs_invoice_nr": "0",
47 "customs_shipment_type": 0,
48 "parcel_items": [
49 {
50 "description": "green bag",
51 "quantity": 1,
52 "weight": "1.000",
53 "value": "110.00",
54 "hs_code": "111111",
55 "origin_country": "NL",
56 "product_id": "3837374",
57 "properties": {
58 "color": "green",
59 "variant": "B"
60 },
61 "sku": "AA6",
62 "return_reason": null,
63 "return_message": null
64 }
65 ],
66 "documents": [],
67 "type": null,
68 "shipment_uuid": "ee742475-c6f2-45d9-8342-28f4f84e9ef7",
69 "shipping_method": 8,
70 "external_order_id": "119172953",
71 "external_shipment_id": "",
72 "external_reference": null,
73 "is_return": false,
74 "note": "",
75 "to_post_number": "111222",
76 "total_order_value": "11.11",
77 "total_order_value_currency": null,
78 "quantity": 1,
79 "colli_tracking_number": "",
80 "colli_uuid": "eaf8af7e-6d2d-4304-8d29-eb485d212028",
81 "collo_nr": 0,
82 "collo_count": 1,
83 "awb_tracking_number": null,
84 "box_number": null,
85 "length": "5.50",
86 "width": "10.00",
87 "height": "10.00",
88 "shipping_method_checkout_name": "ship with x",
89 "carrier": {
90 "code": "sendcloud"
91 }
92 }
93 ]
94}
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 endpoint.
Note that when creating the parcel, you can re-define 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. |
Example request
POST
https://panel.sendcloud.sc/api/v2/parcels
Example request body
1{
2 "parcels": [
3 {
4 "request_label": true,
5 "apply_shipping_rules": true,
6 "order_number": "9966331",
7 "name": "John Doe",
8 "company_name": "company name",
9 "email": "test@test.nl",
10 "address": "Fischerinsel",
11 "house_number": "3",
12 "address_2": "",
13 "city": "Berlin",
14 "postal_code": "10179",
15 "country": "DE",
16 "to_service_point": 10608493,
17 "to_post_number": 111222,
18 "sender_address": 151250,
19 "length": "5.5",
20 "width": "10",
21 "height": "10",
22 "weight": 1,
23 "quantity": 1,
24 "shipment": {
25 "id": 1315
26 },
27 "insured_value": 0,
28 "total_order_value": "11.11",
29 "parcel_items": [
30 {
31 "description": "green bag",
32 "quantity": 1,
33 "weight": "1",
34 "value": "110",
35 "hs_code": "111111",
36 "origin_country": "NL",
37 "sku": "AA6",
38 "product_id": 3837374,
39 "properties": {
40 "color": "green",
41 "variant": "B"
42 }
43 }
44 ],
45 "shipping_method_checkout_name": "ship with x",
46 "shipment_uuid": "ee742475-c6f2-45d9-8342-28f4f84e9ef7",
47 "customs_shipment_type": 0,
48 "customs_invoice_nr": 0
49 }
50 ]
51}
Example response
1{
2 "parcels": [
3 {
4 "id": 119510803,
5 "address": "Fischerinsel 3",
6 "address_2": "",
7 "address_divided": {
8 "street": "Fischerinsel",
9 "house_number": "3"
10 },
11 "city": "Berlin",
12 "company_name": "company name",
13 "country": {
14 "iso_2": "DE",
15 "iso_3": "DEU",
16 "name": "Germany"
17 },
18 "data": {},
19 "date_created": "19-07-2021 08:09:02",
20 "date_announced": "19-07-2021 08:09:03",
21 "date_updated": "19-07-2021 08:09:03",
22 "email": "test@test.nl",
23 "name": "John Doe",
24 "postal_code": "10179",
25 "reference": "0",
26 "shipment": {
27 "id": 1315,
28 "name": "DHL Parcel Connect 0-2kg to ParcelShop"
29 },
30 "status": {
31 "id": 1000,
32 "message": "Ready to send"
33 },
34 "to_service_point": 10608493,
35 "telephone": "",
36 "tracking_number": "JVGL0593131601490618",
37 "weight": "1.000",
38 "label": {
39 "normal_printer": [
40 "https://panel.sendcloud.sc/api/v2/labels/normal_printer/119510803?start_from=0",
41 "https://panel.sendcloud.sc/api/v2/labels/normal_printer/119510803?start_from=1",
42 "https://panel.sendcloud.sc/api/v2/labels/normal_printer/119510803?start_from=2",
43 "https://panel.sendcloud.sc/api/v2/labels/normal_printer/119510803?start_from=3"
44 ],
45 "label_printer": "https://panel.sendcloud.sc/api/v2/labels/label_printer/119510803"
46 },
47 "customs_declaration": {},
48 "order_number": "9966331",
49 "insured_value": 0,
50 "total_insured_value": 0,
51 "to_state": null,
52 "customs_invoice_nr": "9966331",
53 "customs_shipment_type": 0,
54 "parcel_items": [
55 {
56 "description": "green bag",
57 "quantity": 1,
58 "weight": "1.000",
59 "value": "110.00",
60 "hs_code": "111111",
61 "origin_country": "NL",
62 "product_id": "3837374",
63 "properties": {
64 "color": "green",
65 "variant": "B"
66 },
67 "sku": "AA6",
68 "return_reason": null,
69 "return_message": null
70 }
71 ],
72 "documents": [
73 {
74 "type": "label",
75 "size": "a6",
76 "link": "https://panel.sendcloud.sc/api/v2/parcels/119510803/documents/label"
77 }
78 ],
79 "type": "parcel",
80 "shipment_uuid": "ee742475-c6f2-45d9-8342-28f4f84e9ef7",
81 "shipping_method": 1315,
82 "external_order_id": "119172953",
83 "external_shipment_id": "",
84 "external_reference": null,
85 "is_return": false,
86 "note": "",
87 "to_post_number": "111222",
88 "total_order_value": "11.11",
89 "total_order_value_currency": "",
90 "colli_tracking_number": "",
91 "colli_uuid": "f814af77-5f4e-496d-b644-b9692456041c",
92 "collo_nr": 0,
93 "collo_count": 1,
94 "awb_tracking_number": null,
95 "box_number": null,
96 "length": "5.50",
97 "width": "10.00",
98 "height": "10.00",
99 "shipping_method_checkout_name": null,
100 "carrier": {
101 "code": "dhl"
102 },
103 "tracking_url": "https://tracking.sendcloud.sc/forward?carrier=dhl&code=JVGL0593131601490618&destination=DE&lang=en-us&source=NL&type=parcel&verification=10179&created_at=2021-07-19"
104 }
105 ]
106}
Fetch the label
The response to the previous request has links to the label. There are four options to fetch the label:
normal_printerprovides an A4 document with the label on it. The default format is PDF.start_fromdetermines a place for the label: top left, top right, and bottom left. Learn how to use it in the Query parameters.label_printerprovides an A6 label.- The Parcel documents section contains a label link and additional documents for international shipments outside of the EU. Note that it is possible to get the label in different formats including ZPL using the Get a parcel 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.
Additional functionalities
The flow also has the option to create labels for packages to service points, create multicollo parcels, and other functionalities. For more information about those functionalities and how they can be used, refer to the integration guidelines.
