Site Logo

🎉 ShipEngine is becoming ShipStation API 🎉

Over the next few months you'll notice the ShipEngine website, documentation portal, and dashboard being rebranded as ShipStation API. For our ShipEngine customers, you don't need to take any action or change any of your integrations in any way. All endpoints will remain the same and continue to function as they always have.

To learn more about what's coming, review our New ShipStation API page.

Collect on Delivery

Collect on Delivery (C.O.D.) is an advanced option you can add to a shipment with certain supported carriers. This option allows the shipper to not pay the shipping cost, deferring it to the recipient who will pay the shipping cost upon receipt.

Requirements

  • First check that the carrier that you're using supports the Collect on Delivery option. You can list carrier options to see if your carrier support this feature.
  • When you create a shipment, label, or rate, use the advanced_options.collect_on_delivery property to specify the Collect On Delivery options.

C.O.D. Object Properties

PropertiesTypeDescription
payment_typeenumerated stringrequired
Values: any, cash, cash_equivalent, none
amountdecimalrequired
currencyenumerated stringrequired
Values: usd, cad, aud, gbp, eur, nzd

The cash_equivalent payment_type specified in the request can cover a wide range of payment methods depending on the carrier. For example, the recipient can pay with a cashier's check or a money order. Please check with your selected carrier if this will be relevant to you or your customer.

Here is an example of the advanced_options object with the collect_on_delivery property and related values.

1
2
3
4
5
6
7
8
9
10
11
{
"advanced_options": {
"collect_on_delivery": {
"payment_type": "cash",
"payment_amount": {
"amount": 10.7,
"currency": "usd"
}
}
}
}

Select Collect On Delivery

You can designate collect on delivery with the following methods and endpoints:

  • POST /v1/shipments
  • PUT /v1/shipments/{shipment_id}
  • POST /v1/labels
  • POST /v1/rates

Example Shipment Request & Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
POST /v1/shipments HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipments": [
{
"advanced_options": {
"collect_on_delivery": {
"payment_type": "cash",
"payment_amount": {
"amount": 10.7,
"currency": "usd"
}
}
},
"service_code": "ups_ground",
"validate_address": "no_validation",
"ship_to": {
"name": "Amanda Miller",
"phone": "555-555-5555",
"address_line1": "525 S Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"country_code": "US",
"address_residential_indicator": "yes"
},
"ship_from": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
},
"confirmation": "none",
"insurance_provider": "none",
"tags": [],
"packages": [
{
"weight": {
"value": 1,
"unit": "ounce"
}
}
]
}
]
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
{
"shipments": [
{
"advanced_options": {
"bill_to_account": null,
"bill_to_country_code": null,
"bill_to_party": null,
"bill_to_postal_code": null,
"contains_alcohol": false,
"delivered_duty_paid": false,
"non_machinable": false,
"saturday_delivery": false,
"dry_ice": false,
"dry_ice_weight": null,
"freight_class": null,
"custom_field1": null,
"custom_field2": null,
"custom_field3": null,
"collect_on_delivery": {
"payment_type": "cash",
"payment_amount": {
"currency": "usd",
"amount": 10.7
}
}
},
"errors": [],
"address_validation": null,
"shipment_id": "se-1020109",
"carrier_id": "se-95",
"service_code": "ups_ground",
"external_shipment_id": null,
"ship_date": "2019-09-25T00:00:00Z",
"created_at": "2019-09-25T19:03:49.0116799Z",
"modified_at": "2019-09-25T19:03:49.0126795Z",
"shipment_status": "pending",
"ship_to": {
"name": "Amanda Miller",
"phone": "555-555-5555",
"address_line1": "525 S Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"country_code": "US",
"address_residential_indicator": "yes"
},
"ship_from": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
},
"warehouse_id": null,
"return_to": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
},
"confirmation": "none",
"customs": null,
"external_order_id": null,
"order_source_code": null,
"insurance_provider": "none",
"tags": [],
"packages": [
{
"package_code": "package",
"weight": {
"value": 1.0,
"unit": "ounce"
},
"dimensions": {
"unit": "inch",
"length": 0.0,
"width": 0.0,
"height": 0.0
},
"insured_value": {
"currency": "usd",
"amount": 0.0
},
"label_messages": {
"reference1": null,
"reference2": null,
"reference3": null
},
"external_package_id": null
}
],
"total_weight": {
"value": 1.0,
"unit": "ounce"
},
"items": []
}
]
}

Example Label Request & Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
POST /v1/labels HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"shipment": {
"advanced_options": {
"collect_on_delivery": {
"payment_type": "any",
"payment_amount": {
"amount": 10.7,
"currency": "usd"
}
}
},
"service_code": "ups_ground",
"external_shipment_id": "__YOUR_EXTERNAL_ID_HERE__",
"ship_to": {
"name": "John Stuckey",
"phone": "6625905259",
"company_name": "John Stuckey",
"address_line1": "3412 Pemberton Square Blvd",
"address_line2": "Ste 2-241",
"city_locality": "VICKSBURG",
"postal_code": "39180-5541",
"country_code": "US",
"state_province": "MS",
"address_residential_indicator": "unknown"
},
"ship_from": {
"name": "Fulfillment Center",
"phone": "877-743-2269",
"company_name": "BBQGuys",
"address_line1": "8151 Airline Hwy",
"city_locality": "Baton Rouge",
"postal_code": "70815",
"country_code": "US",
"state_province": "LA"
},
"confirmation": "none",
"packages": [
{
"weight": {
"value": 2,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 2,
"width": 14,
"height": 17
}
}
]
}
}

Response

The collect on delivery payment option is not shown in the create label response.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
{
"label_id": "se-6615",
"status": "completed",
"shipment_id": "se-1020115",
"ship_date": "2019-09-26T00:00:00Z",
"created_at": "2019-09-26T17:48:59.2732285Z",
"shipment_cost": {
"currency": "usd",
"amount": 27.27
},
"insurance_cost": {
"currency": "usd",
"amount": 0.0
},
"tracking_number": "1Z14Y0487211178222",
"is_return_label": false,
"rma_number": null,
"is_international": false,
"batch_id": "",
"carrier_id": "se-95",
"service_code": "ups_ground",
"package_code": "package",
"voided": false,
"voided_at": null,
"label_format": "pdf",
"label_layout": "4x6",
"trackable": true,
"carrier_code": "ups",
"tracking_status": "in_transit",
"label_download": {
"pdf": "http://localhost:55163/v1/downloads/1/7OC4emEGkEmtutHwzbhvwg/label-6615.pdf",
"png": "http://localhost:55163/v1/downloads/1/7OC4emEGkEmtutHwzbhvwg/label-6615.png",
"zpl": "http://localhost:55163/v1/downloads/1/7OC4emEGkEmtutHwzbhvwg/label-6615.zpl",
"href": "http://localhost:55163/v1/downloads/1/7OC4emEGkEmtutHwzbhvwg/label-6615.pdf"
},
"form_download": null,
"insurance_claim": null,
"packages": [
{
"package_code": "package",
"weight": {
"value": 2.00,
"unit": "pound"
},
"dimensions": {
"unit": "inch",
"length": 2.00,
"width": 14.00,
"height": 17.00
},
"insured_value": {
"currency": "usd",
"amount": 0.00
},
"tracking_number": "1Z14Y0487211178222",
"label_messages": {
"reference1": null,
"reference2": null,
"reference3": null
},
"external_package_id": null
}
]
}

Cancel the C.O.D. Option

To cancel the collect on delivery option in a shipment, you must update the shipment. In the update request, set the payment type to none and the amount to 0.