Skip to Content
FastracDocs

Ship with cash on delivery

Let the courier collect payment at the door, book COD orders, and follow the money until payout.

Product
APIShipping Engine API
Section
Guides
Reading time
6 min read

Goal: offer cash on delivery (COD, bayar di tempat): the courier collects the money from the receiver, and Shipping Engine pays your share out to you after delivery.

Before you start:

  • Your API key has the USE_COD permission. COD is unlocked when your business verification is approved. If you get a USE_COD error, ask your account admin or Fastrac support.
  • You know how COD amounts are calculated. See Insurance and COD.
  1. Quote with COD turned on

    Add codOption to the rate request. Set isCod: true, and optionally codCustomAmount to collect a specific amount (for example a rounded total).

    curl -s -X POST "$FASTRAC_API/b2b/shipping-rate" \
      -H "Authorization: Bearer $FASTRAC_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "origin":       { "fullAddress": "Jl. Tebet Raya No. 12, Jakarta Selatan", "subdistrictId": "3174091001" },
        "destinations": [{ "fullAddress": "Jl. Braga No. 8, Kota Bandung",         "subdistrictId": "3273011003" }],
        "courierCode": "REGULAR",
        "insurance": false,
        "codOption": { "isCod": true },
        "packages": [{
          "itemValue": 250000, "isGlassware": false, "weight": 800,
          "dimension": { "length": 20, "width": 15, "height": 10 }
        }]
      }'

    itemValue is the price of the goods you want to collect. It must be between Rp 15.000 and Rp 100.000.000.

  2. Keep only COD-capable rates

    With REGULAR or ALL, services that can't do COD are still returned, without COD. Keep only rates with isSupportCod: true. For those, priceDetail.codBreakdown shows the money:

    Rate (trimmed)
    {
      "shippingRateCode": "SR-C0D9X2LM",
      "courierCode": "JNE",
      "isSupportCod": true,
      "priceDetail": {
        "totalPrice": 9099,
        "taxBreakdown": { "ppnInsurance": 0, "ppnShipment": 99, "ppnCod": 688 },
        "codBreakdown": {
          "itemValue": 250000,
          "codBilled": 266037,
          "codDisbursement": 250000,
          "codFee": 6250,
          "codFeePercent": 2.5,
          "codCustom": 0
        }
      }
    }
    FieldShow it as
    codBilledWhat your customer pays the courier at the door. Show this at checkout.
    codDisbursementWhat you receive after delivery.
    totalPrice, codFee, taxBreakdown.ppnCodCosts taken out of the collected cash.
  3. Create the COD order

    Book exactly as for a regular shipment. COD comes from the rate, so there is no COD field in the order:

    curl -s -X POST "$FASTRAC_API/b2b/orders" \
      -H "Authorization: Bearer $FASTRAC_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{
        "shipments": [{
          "shippingRateCode": "SR-C0D9X2LM",
          "sender":    { "name": "Toko Contoh", "email": "[email protected]", "phoneNumber": "081234567890" },
          "receivers": [{ "name": "Budi Santoso", "phoneNumber": "081298765432",
                          "addressNote": "Pagar hitam", "label": "Rumah", "stopSequence": 1 }],
          "shippingOptions": { "fulfillmentMethod": "DROPOFF" }
        }]
      }'
    InboundResponse (trimmed)
    {
      "data": {
        "code": "FSO-261120-Q8R7S6",
        "price": { "amount": 0, "currency": "IDR", "codBilled": 266037, "codDisbursement": 250000 },
        "shipments": [{ "code": "SHP-261120-T5U4V3", "isCod": true, "status": "PENDING_DROPOFF", "airwayBill": "CGK9876543210" }]
      }
    }

    price.amount is 0: nothing is deducted from your balance for a COD order. The shipping costs are taken out of the cash the courier collects.

    Don't mix COD and non-COD in one order

    Every shipment in an order must be COD, or none. A mix is rejected with All shipments in one order must be either COD or non-COD. Create two orders instead.

  4. Follow delivery and payout

    Track the shipment as usual (Track shipments). When it reaches DELIVERED, the courier has collected codBilled.

    Your share (codDisbursement) is credited to your payout balance after delivery, once the courier has settled the cash. Timing depends on the courier. Follow it in your balance logs, and withdraw the payout balance, or move it to your shipping credit, from the dashboard.

If a COD shipment is cancelled or returned

What happensMoney effect
You cancel before pickupNothing was charged, so there is nothing to refund. If a COD amount had already been credited for the shipment, it is reversed (a DEBIT log ending in (COD reversal)).
The receiver refuses or can't be reached, and the parcel returns (RTS)No cash is collected, so you receive nothing for it. Any COD amount credited for it is reversed.
Return feeJNE, J&T, ID Express, SAP and Anteraja charge a return fee equal to the original shipping fee. It is deducted from your shipping credit (then payout balance) and announced by the shipment.rts_billed webhook. See Returns (RTS).

COD orders are more likely to be refused at the door than prepaid ones. Confirm the order with the customer (for example by WhatsApp) before you hand the parcel over.

Limits

LimitValue
PermissionUSE_COD on your API key. Without it, quoting returns 403 You are not allowed to use COD for shipping rate COD. and booking returns 403 You are not allowed to use COD for COD orders.
ServicesOnly rates with isSupportCod: true. Booking a COD rate on a service without COD fails with Courier service '…' (…) does not support COD.
Goods valueitemValue between Rp 15.000 and Rp 100.000.000.
Courier capsSome couriers cap the COD amount. SPX accepts up to Rp 5.000.000.
Custom amountcodCustomAmount must at least cover totalPrice + codFee + ppnCod.
OrdersCOD and non-COD shipments can't share an order.

Checklist

  • Quote with codOption.isCod: true and keep only isSupportCod: true rates.
  • Show codBilled to your customer as the amount to pay at the door.
  • Put COD and non-COD shipments in separate orders.
  • Expect price.amount: 0; no balance is deducted.
  • Watch your balance logs for the payout after delivery.
  • Keep enough shipping credit for return fees on refused COD parcels.

Was this page helpful?

On this page