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.

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 via the API reference to see if your carrier supports 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`
`payment_amount`	object	required Contains the C.O.D. amount and currency
`payment_amount.amount`	decimal	required The C.O.D. collection amount
`payment_amount.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 /v2/shipments
PUT /v2/shipments/{shipment_id}
POST /v2/labels
POST /v2/rates

Example Shipment Request & Response

POST /v2/shipments HTTP/1.1
Host: api.shipstation.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

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

POST /v2/labels HTTP/1.1
Host: api.shipstation.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.

{
  "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": "https://api.shipstation.com/v2/downloads/1/7OC4emEGkEmtutHwzbhvwg/label-6615.pdf",
    "png": "https://api.shipstation.com/v2/downloads/1/7OC4emEGkEmtutHwzbhvwg/label-6615.png",
    "zpl": "https://api.shipstation.com/v2/downloads/1/7OC4emEGkEmtutHwzbhvwg/label-6615.zpl",
    "href": "https://api.shipstation.com/v2/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 via the API. In the update request, set the payment type to none and the amount to 0.