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_CODpermission. COD is unlocked when your business verification is approved. If you get aUSE_CODerror, ask your account admin or Fastrac support. - You know how COD amounts are calculated. See Insurance and COD.
Quote with COD turned on
Add
codOptionto the rate request. SetisCod: true, and optionallycodCustomAmountto 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 } }] }'itemValueis the price of the goods you want to collect. It must be between Rp 15.000 and Rp 100.000.000.Keep only COD-capable rates
With
REGULARorALL, services that can't do COD are still returned, without COD. Keep only rates withisSupportCod: true. For those,priceDetail.codBreakdownshows 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 } } }Field Show 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. 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.amountis0: 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.Follow delivery and payout
Track the shipment as usual (Track shipments). When it reaches
DELIVERED, the courier has collectedcodBilled.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 happens | Money effect |
|---|---|
| You cancel before pickup | Nothing 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 fee | JNE, 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
| Limit | Value |
|---|---|
| Permission | USE_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. |
| Services | Only rates with isSupportCod: true. Booking a COD rate on a service without COD fails with Courier service '…' (…) does not support COD. |
| Goods value | itemValue between Rp 15.000 and Rp 100.000.000. |
| Courier caps | Some couriers cap the COD amount. SPX accepts up to Rp 5.000.000. |
| Custom amount | codCustomAmount must at least cover totalPrice + codFee + ppnCod. |
| Orders | COD and non-COD shipments can't share an order. |
Checklist
- Quote with
codOption.isCod: trueand keep onlyisSupportCod: truerates. - Show
codBilledto 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?