Royal Mail Click & Drop API: Order To Manifest

If you've searched for a coherent build guide to the Royal Mail Click & Drop API, you've probably found fragments: a help-centre article here, a PHP SDK README there, a forum thread about a 202 response nobody expected. This walkthrough covers the Royal Mail Click and Drop API end to end, from order creation to a closed manifest, including the rate-limit mechanics and the mandatory MFA change that landed in September 2026.

Why Click & Drop, not Pro Shipping or OLP

Click & Drop API is the right tier if you hold a Royal Mail Online Business Account (OBA) and want programmatic order creation without committing to Pro Shipping's volume thresholds. It sits between manual Click & Drop web use and a full EDI-style integration.

One gotcha that trips up a lot of integrators: the Click & Drop API cannot retrieve labels for OLP (Online Postage) accounts, only OBA. If your account type is wrong, you'll get order creation working and then stall at label retrieval, which is a frustrating place to discover a tier mismatch. Check your account type in Click & Drop settings before you write a line of code.

Before you start

You need five things in place before your first API call: an active Royal Mail OBA account, registration on the Click & Drop developer portal, an API key, a server-side proxy so the key never touches a browser or mobile client, and an internal order reference you control. That last one matters because Click & Drop has no documented idempotency key — you own de-duplication yourself.

Authentication is an API key attached via the Authorization header, not OAuth, which keeps the integration simple but means the key is a long-lived secret that needs rotation discipline like any other.

Plan your batching before you write any code. You can include up to 2000 orders on a single request, and accounts are limited to 2 API calls per second. That ceiling is account-wide, not per-endpoint, so an order-creation burst and a label-polling loop compete for the same 2-calls-per-second budget.

The order-to-manifest flow, step by step

This is the sequence against api.parcel.royalmail.com/api/v1, from a validated order in your OMS to a manifest the driver can act on.

1. Authenticate. Attach your API key as the Authorization header on every call. Cache nothing session-based — the key is static per account, not a short-lived token.
2. Build the order payload. Map your OMS order to Click & Drop's order schema. serviceCode controls the Royal Mail service: CRL for Tracked 48, TPN for Tracked 24, STL for Special Delivery. Include carrierName if multi-carrier is enabled on the account, and leave product-catalogue fields blank rather than reusing one SKU across every order — passing default product information at this stage, or producing the same SKU for every order will result in slower order processing.
3. Submit. POST /orders with up to 2000 orders per call. Build a client-side token bucket set to 2 requests/second so you never rely on Royal Mail's throttle to self-correct your pacing.
4. Poll for processed status. GET /orders/full to confirm acceptance and retrieve the orderIdentifier. Poll once, on a sane backoff — repeated polling of the same order is explicitly discouraged, since Click & Drop limits the number of calls you can make within the same time period, and it is not advised to send multiple calls to perform the same action, such as attempting to retrieve order information for the same order multiple times, as this can result in slower order processing for your account.
5. Retrieve the label. Fetch the generated PDF, or route to ZPL if you're printing on thermal hardware at a pack bench.
6. Submit the manifest. POST /manifests closes the day's eligible orders. Note this call is asynchronous: it answers 202 with a manifests array, and the manifest and its PDF are produced afterwards, read with GET /manifests/{guid} — don't treat the 202 as a finished job, or you'll ship a day with no Sales Order Summary printed.
7. Verify. GET /manifests/{manifestIdentifier} to confirm the manifest document is ready before you rely on it operationally.
8. Recover failed manifests. POST /manifests/retry/{manifestIdentifier} if the first attempt partially failed, rather than resubmitting the original orders as a fresh batch.

How you know it worked

Success looks like a manifest ID returned, a downloadable Sales Order Summary, a label count that equals your order count, and nothing left in a pending state when your collection window opens. Royal Mail requires you to create and print a Sales Order Summary, which you must then hand to the driver who picks up the parcels, and you generate it through the manifest process. No summary, no proof of what you handed over — this is the document your driver actually checks.

Build a synthetic check around this: a scheduled job that asserts manifest count is greater than zero before the courier collection window, alerting the moment an automated run didn't fire. This is the same pattern we've covered for other carriers on this blog — a missing manifest is a silent failure until a driver turns up to nothing.

Failure mode: 429s and duplicate orders under load

Royal Mail's own throttling documentation distinguishes plan limits from burst limits, and the distinction matters for how you write your retry logic. Some plans apply a single limit across all included API resources, while others may set different limits per resource, and some APIs may have both Plan Limits and Burst Limits — Burst Limits are throttling rules set for short intervals like 5-10 seconds and will generally reside over a plan limit which can have hourly or daily interval. If your application exceeds its allocated limit, the API will respond with 429 HTTP Error code for additional requests until the window resets. A naive exponential-backoff retry that doesn't respect this window will simply walk straight into the next burst ceiling.

The second failure mode is quieter and more expensive: duplicate orders. Because Click & Drop has no native idempotency key, a POST /orders call that times out and gets retried can create a second order for the same shipment, double-charging the customer's postage line and confusing your warehouse pick list. The fix is the same pattern this blog advocates for any carrier adapter: check your own order store for the internal reference before resubmitting, and only retry against Royal Mail once you've confirmed the original attempt genuinely failed rather than just timed out on your side.

The 2026 MFA change and what it means for service accounts

If you provisioned a Click & Drop account purely for headless API access and nobody has logged into the web UI since mid-August 2026, that account is now a liability. Royal Mail's September 2026 release confirmed that from the Click & Drop Release of 10/09/2026, new accounts, and existing accounts that haven't logged in since 18/08/2026, will now be required to set up multi-factor authentication.

API keys themselves aren't the MFA gate — but the account they're tied to is, and a dormant credential sitting behind an account that triggers an MFA challenge on next login can block a human from resolving an incident at exactly the wrong moment. Schedule a human login at least quarterly for any account used purely for headless access, and document the MFA re-enrolment step in your incident runbook so a dormant integration doesn't silently fail at manifest time, three weeks after everyone assumed it was fine.

Worth flagging alongside this: the same release cadence brought CN23 automation for OBA accounts — Royal Mail has moved to using CN23s for its international exports except instances where combined labels are selected, and CN23 documents are now automatically generated for international orders. If you've hardcoded customs-document handling for international shipments, check it against this change before your next international order batch.

When to build vs buy the connector

Building directly against api.parcel.royalmail.com/api/v1 gets you full control and no licence cost, but you own rate-limit handling, retry logic, schema drift, and the MFA runbook above. If Royal Mail is one of several carriers in your routing logic rather than a single dedicated integration, a managed multi-carrier platform absorbs that maintenance burden.

The trade-off is simple to state and harder to live with: direct integration is free and fully under your control, a managed platform like Cargoson, nShift, or ShipEngine costs more but means someone else wakes up when Royal Mail changes its rate-limit headers.

Whichever route you take, the first thing to verify is your account type (OBA, not OLP), and the second is whether your service account has logged into the Click & Drop UI since 18 August 2026. Both are five-minute checks that save a much worse afternoon later.