The REST API: driving COD orders from your own code

What the API is for — and when it is useless

The API answers three situations, and roughly only three. The first is a bespoke store: at the moment the customer confirms the basket, your code creates the lead and immediately receives its reference, which it can show to the customer. The second is a mobile app, which has no web page to be called. The third is an internal tool — a dashboard, an accounting reconciliation, a reporting script — that needs to read order states to combine them with its own data.

Outside those three cases it is not much use, and that is better said before someone spends a week on it. If your orders come from an existing store, the store connection brings them in with no code and with a fallback re-read you would not have written. If they come from a form or a landing page, a spreadsheet is quicker to set up and easier to fix. If you simply want to be told when a parcel is delivered, what you need is an outgoing webhook, not a loop of API calls.

The useful rule is this: the API is justified when a program you control is what produces the order. In every other case, one of the three other routes does the same job for less effort and less maintenance.

The API key, and what it is worth

Authentication fits in one line: every call carries a key in its authorisation header. There is no login to transmit, no account parameter, no session to maintain. The seller is derived from the key, and that is as much a security decision as a convenience one: no call can reach another account's data, however the parameters are changed.

A key is created in the seller workspace, with a name saying what it is for. It is shown once only, at creation: only its digest is kept, and nobody — not even support — can read it back to you. If it is lost, create another. If it is revoked, it never becomes valid again.

• One key per integration — One for the mobile app, another for the reporting script. Revoking one does not stop the other, and the call log says which did what.
• A key can be attached to a store — Leads created with that key then automatically carry the matching store, without your code having to say so.
• The key is a server secret — It must never ship inside a web page, a distributed mobile app or a code repository: whoever reads it can create orders in your name.
• Last use is visible — A key that has not been used for a long time is a key to revoke.
• The call log is yours — Method, address called, response code: that is what answers "why is this not working" without guesswork.

What can be read, what can be written, what stays untouched

The scope is deliberately narrow: the API exists to bring orders in and to find out where they are. Anything that commits money or alters a journey stays in the interface, because a programming mistake there would cost more than a human click.

• Two possible answers on creation — An accepted lead answers "created". A doubtful one — unknown reference, unrecognised city, incoherent total, recent duplicate — answers "accepted" with the list of anomalies: it exists, as a damaged lead, waiting for a correction. It is never silently refused.
• Cursor pagination — The lead list is walked by passing back the identifier returned with the previous page, not a page number. A page number would shift with every new lead, and the integration would skip orders without noticing.
• Your own reference is kept — The external reference field is passed through as written and shown again in the interface: that is what lets you reconcile a lead with the original order in your system.
• What the API does not do — It does not change a status, cancel an order, trigger a withdrawal or read anything belonging to another seller. Those actions live in the interface, where they are traced.

Rate limits and error codes

A rate limit applies per key, per minute. It exists for a simple reason: one seller's badly written loop must not slow the platform down for everyone else. The figure in force is not a constant to copy into your code — it is returned by the key-verification call, so it can be adapted without waiting for an announcement.

When the limit is reached, the response says so explicitly and states how long to wait. A properly written client honours that delay rather than retrying at once; retrying immediately only burns the next minute.

Where the full reference lives

This page explains what the API is for and what it allows; it does not replace the reference. That lives in the developer documentation, which is public and needs no account — a seller's developer does not have their login, and demanding a sign-up to read an API contract would protect nothing.

There you will find the getting-started guide, the address reference with every expected field, the outgoing webhooks page, the list of errors and limits, and the version log. The description is written once and serves everything: the page a human reads, an OpenAPI file your tool imports to generate a client, and a collection ready to try. That is what guarantees the page and the file do not say two different things six months later.

The API version number is returned in the header of every response, and the version log says what changed. Added fields are common and break nothing: a well-written client ignores a field it does not know rather than failing on it.