Cash on delivery, shipped
Cash on delivery is one of the tenders The Merchant Engine ships with, next to manual bank transfer and gift cards. A store owner switches it on in the admin, the public checkout endpoint publishes it with its translated name, and the order records the tender it was placed with. No card gateway is required to take an order, and card payment through Stripe sits beside it when the operator switches it on.
How it works
The tender is a row, not a plugin. Payment methods live in the database with a code, a provider family, a
translated name and description, and an active flag. Cash on delivery is the cod provider. The admin's
payment methods screen is where a store owner turns it on or off.
The storefront learns the tenders from one public route. GET /v1/checkout/settings returns
whether a guest may check out, which fields the operator requires and the tenders on offer. It is the only route
that publishes payment methods, and the code sent back on the order has to come from that list. The
route is Cache-Control: no-store on purpose, so an operator switching a tender off applies on the next
page load.
GET /v1/checkout/settings
{
"data": {
"checkout": {
"guestCheckoutEnabled": true,
"requiredFields": ["email"],
"termsOfServiceUrl": null,
"postPurchaseRedirectUrl": null,
"checkoutMessage": null
},
"paymentMethods": [
{
"code": "cod",
"name": "Cash on delivery",
"description": "Pay the courier in cash when your order arrives.",
"provider": "cod",
"sortOrder": 0
}
]
}
} The order keeps what it was placed with. The payment method name, the shipping method name and the line labels are snapshotted onto the order in the locale it was placed in, so a French order still reads Paiement à la livraison a year later even if the store renames the tender. Stock is decremented atomically at order creation, so two customers cannot both take the last unit.
What is not there. Stripe is the only card provider so far. More plug in behind one interface, and the docs carry a recipe for adding one. There is also no cash-on-delivery surcharge field: the customer pays the order total on the doorstep, and any delivery fee comes from the shipping zone.
Where to read the detail
- Checkout and orders: the settings route, the order body, the tender code and every error code the checkout can answer.
- The first hour: placing a cash-on-delivery test order right after the install.
- Add a payment provider: the recipe for wiring another card provider when you need one.
Questions
Is cash on delivery a plugin?
No. It is one of the payment methods the engine ships with, alongside manual bank transfer and gift cards. A store owner switches it on in the admin and it appears at checkout.
How is this different from cash on delivery on Shopify?
For the shopper, not much. On Shopify, cash on delivery is a manual payment method, and Shopify's help centre says manual payments carry no third-party transaction fee. The difference is where the store lives. Shopify hosts the store and its checkout. This engine runs on your server and the checkout code is in the repository, so you can change how a cash order is placed. The Shopify comparison goes row by row.
How does the storefront know the store takes cash?
It reads GET /v1/checkout/settings, a public route that returns the tenders the store offers with their translated names and descriptions. The code the customer picks goes back on the order.
Can a store run without any card gateway at all?
Yes, and that is the default configuration. Cash on delivery, manual bank transfer and gift cards need no credential. Card payment through Stripe is an option the operator switches on in the admin by entering the keys.
Does the engine add a cash-on-delivery surcharge?
No. There is no surcharge field on a payment method. What the customer pays on delivery is the order total, and any delivery fee comes from the shipping zone and method the store configured.
What stops a double order when the customer taps twice?
Every order creation carries an idempotency key, and a repeat of the same request with the same key returns the first order instead of placing a second one. See idempotent checkout.
Does the customer get anything to keep?
An order confirmation email from the store’s own domain, an order they can track, and an invoice PDF rendered in their locale and direction.
Last updated . Every claim on this page is read from a published source and cited beside it.