Shipping rules
You can create shipping rules in your Sendcloud account and use them in conjunction with our API to automate your parcel processing workflow.
Shipping rules are pre-defined actions which will automatically apply to created parcels or imported orders when they match a given condition. An example of a shipping rule would be:
- “If [parcel weight] is less than [10kg], ship with [PostNL Home address only 0-23kg].
Apply shipping rules to created parcels
When you create a parcel via the API, you can indicate whether you want your shipping rules to apply to it.
The benefit of this is that you can already indicate how you want to ship a parcel without having to manually input multiple different fields in your API request. For example, you can use shipping rules to determine the shipping method, sender address or insurance value you want to apply to parcels based on the ‘from’ address, shipping country, which parcel items are included, and many more.
How it works
When you Create a parcel via the Shipping API, you can indicate whether you want to apply shipping rules via the apply_shipping_rules field. Depending on whether or not you choose to immediately request the label, shipping rule behaviour will change as described below:
Method 1: Create a parcel with a shipping label
In this scenario, you create a parcel, announce it with the carrier and create the shipping label, all in a single API call. This is done by flagging request_label: true. This interaction is described in more detail in our documentation.
- In the request body, use the
shipping_method_id“Unstamped letter”id: 8. - This will bypass the required
shipping_methodfield by using the test label method, ensuring that any shipping rules you have configured related to shipping method selection will apply correctly to your label. - Flag the
apply_shipping_rulesfield totrue. - If the parcel properties match, then shipping rules will be applied and the label will be created alongside the parcel.
Example
For this example, we have configured a shipping rule that states:
- “If [to country] is [Netherlands], ship with [PostNL Standard].
Example request:
1curl --location -g --request POST 'https://panel.sendcloud.sc/api/v2/parcels' \
2--header 'Authorization: Basic <credentials>' \
3--data-raw '
4{
5 "parcel": {
6
7 "name": "John Doe",
8 "company_name": "FlowerShop",
9 "email": "john@doe.com",
10 "telephone": "+31611223344",
11 "address": "Stadhuisplein 10",
12 "house_number": "10",
13 "address_2": "",
14 "city": "Eindhoven",
15 "country": "NL",
16 "postal_code": "5616 EM",
17 "country_state": null,
18 "parcel_items": [
19 {
20 "description": "T-Shirt",
21 "hs_code": "6109",
22 "origin_country": "SE",
23 "product_id": "898678671",
24 "properties": {
25 "color": "Blue",
26 "size": "Medium"
27 },
28 "quantity": 2,
29 "sku": "TST-OD2019-B620",
30 "value": "19.95",
31 "weight": "0.9"
32 }
33 ],
34 "weight": "3.49",
35 "length": "31.5",
36 "width": "27.2",
37 "height": "12.7",
38 "total_order_value": "896.92",
39 "total_order_value_currency": "EUR",
40 "shipment": {
41 "id": 8
42 },
43 "sender_address": 1,
44 "quantity": 1,
45 "total_insured_value": 0,
46 "is_return": false,
47 "request_label": false,
48 "apply_shipping_rules": false,
49 "request_label_async": false
50
51
52 }
53}'
Example response:
1{
2 "parcel":
3 {
4 "id": 1,
5 "address": "Stadhuisplein 10",
6 "address_2": "",
7 "address_divided":
8 {
9 "street": "Stadhuisplein",
10 "house_number": "10"
11 },
12 "city": "Eindhoven",
13 "company_name": "FlowerShop",
14 "country":
15 {
16 "iso_2": "NL",
17 "iso_3": "NLD",
18 "name": "Netherlands"
19 },
20 "data":
21 {},
22 "date_created": "29-06-2022 15:43:18",
23 "date_announced": null,
24 "date_updated": "29-06-2022 15:43:18",
25 "email": "john@doe.com",
26 "name": "John Doe",
27 "postal_code": "5616 EM",
28 "reference": "0",
29 "shipment":
30 {
31 "id": 6,
32 "name": "PostNL home address only 0-23kg"
33 },
34 "status":
35 {
36 "id": 999,
37 "message": "No label"
38 },
39 "to_service_point": null,
40 "telephone": "+31611223344",
41 "tracking_number": "",
42 "weight": "3.490",
43 "label":
44 {},
45 "customs_declaration":
46 {},
47 "order_number": "",
48 "insured_value": 0,
49 "total_insured_value": 0,
50 "to_state": null,
51 "customs_invoice_nr": "",
52 "customs_shipment_type": null,
53 "parcel_items":
54 [
55 {
56 "description": "T-Shirt",
57 "quantity": 2,
58 "weight": "0.900",
59 "value": "19.95",
60 "hs_code": "6109",
61 "origin_country": "SE",
62 "product_id": "898678671",
63 "properties":
64 {
65 "size": "Medium",
66 "color": "Blue"
67 },
68 "sku": "TST-OD2019-B620",
69 "return_reason": null,
70 "return_message": null
71 }
72 ],
73 "documents":
74 [],
75 "type": null,
76 "shipment_uuid": "601e9ba4-0295-4485-a0ac-6098387c6283",
77 "shipping_method": 8,
78 "external_order_id": "1",
79 "external_shipment_id": "",
80 "external_reference": null,
81 "is_return": false,
82 "note": "",
83 "to_post_number": "",
84 "total_order_value": "896.92",
85 "total_order_value_currency": "EUR",
86 "quantity": 1,
87 "colli_uuid": "dde5d500-9a81-4990-8ef1-03c4c786f368",
88 "collo_nr": 0,
89 "collo_count": 1,
90 "awb_tracking_number": null,
91 "box_number": null,
92 "length": "31.50",
93 "width": "27.20",
94 "height": "12.70",
95 "shipping_method_checkout_name": null,
96 "carrier":
97 {
98 "code": "sendcloud"
99 }
100 }
101}
From the response, you can see that the shipping rule has been applied, and the label has been created with the correct shipping method. The label can be downloaded via the URLs included in the response body.
Method 2: Create a parcel without a shipping label
In this scenario, you create a parcel but do not immediately request the label by flagging request_label: false. This allows you to create parcels in bulk, then process them at a later date, either via the API, by using Pack & Go, or from the Sendcloud panel.
- Parcel is created with the status “Ready to process” in the Sendcloud panel, with your shipping rules already applied.
- You can continue making changes to the parcel up until the point where you request the shipping label.
- You can override any applied shipping rules by making a PUT request to the Update a parcel endpoint.
In the example below, we will request the label for our parcel, and override the applied shipping rule by updating the shipping method to “DHLForYou Drop-off”.
Example request:
1curl --location -g --request POST 'https://panel.sendcloud.sc/api/v2/parcels' \
2--header 'Authorization: Basic <credentials>' \
3--data-raw '
4{
5 "parcel":
6 {
7 "id": 1,
8 "request_label": true,
9 "shipment":
10 {
11 "id": 117,
12 "name": "DHLForYou Drop Off"
13 }
14 }
15}'
Example response:
1{
2 "parcel":
3 {
4 "id": 1,
5 "address": "Stadhuisplein 10",
6 "address_2": "",
7 "address_divided":
8 {
9 "street": "Stadhuisplein",
10 "house_number": "10"
11 },
12 "city": "Eindhoven",
13 "company_name": "FlowerShop",
14 "country":
15 {
16 "iso_2": "NL",
17 "iso_3": "NLD",
18 "name": "Netherlands"
19 },
20 "data":
21 {},
22 "date_created": "29-06-2022 15:43:18",
23 "date_announced": null,
24 "date_updated": "29-06-2022 15:43:18",
25 "email": "john@doe.com",
26 "name": "John Doe",
27 "postal_code": "5616 EM",
28 "reference": "0",
29 "shipment":
30 {
31 "id": 117,
32 "name": "DHLForYou Drop Off"
33 },
34 "status":
35 {
36 "id": 999,
37 "message": "No label"
38 },
39 "to_service_point": null,
40 "telephone": "+31611223344",
41 "tracking_number": "",
42 "weight": "3.490",
43 "label":
44 {},
45 "customs_declaration":
46 {},
47 "order_number": "",
48 "insured_value": 0,
49 "total_insured_value": 0,
50 "to_state": null,
51 "customs_invoice_nr": "",
52 "customs_shipment_type": null,
53 "parcel_items":
54 [
55 {
56 "description": "T-Shirt",
57 "quantity": 2,
58 "weight": "0.900",
59 "value": "19.95",
60 "hs_code": "6109",
61 "origin_country": "SE",
62 "product_id": "898678671",
63 "properties":
64 {
65 "size": "Medium",
66 "color": "Blue"
67 },
68 "sku": "TST-OD2019-B620",
69 "return_reason": null,
70 "return_message": null
71 }
72 ],
73 "documents":
74 [],
75 "type": null,
76 "shipment_uuid": "601e9ba4-0295-4485-a0ac-6098387c6283",
77 "shipping_method": 8,
78 "external_order_id": "1",
79 "external_shipment_id": "",
80 "external_reference": null,
81 "is_return": false,
82 "note": "",
83 "to_post_number": "",
84 "total_order_value": "896.92",
85 "total_order_value_currency": "EUR",
86 "quantity": 1,
87 "colli_uuid": "dde5d500-9a81-4990-8ef1-03c4c786f368",
88 "collo_nr": 0,
89 "collo_count": 1,
90 "awb_tracking_number": null,
91 "box_number": null,
92 "length": "31.50",
93 "width": "27.20",
94 "height": "12.70",
95 "shipping_method_checkout_name": null,
96 "carrier":
97 {
98 "code": "dhl"
99 }
100 }
101}
