Collect on Delivery | ShipEngine

🎉 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.

INFO:

FedEx Ground Collect

FedEx Ground Collect is distinct from Collect on Delivery. Review our FedEx guide for details.

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

Properties	Type	Description
`payment_type`	enumerated string	required Values: `any`, `cash`, `cash_equivalent`, `none`
`amount`	decimal	required
`currency`	enumerated string	required 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.

{
  "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

{
  "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

{
  "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": []
    }
  ]
}

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.