Register your software application on the HMRC Developer Hub, subscribe to the Customs Declarations API, and complete the production credentials process through the Software Developer Hub Support team.
Implement the OAuth 2.0 authorisation code flow to obtain a user-scoped access token; note that tokens expire after 4 hours and must be refreshed using the refresh token.
Build the WCO-DMS-compliant XML declaration payload using the CDS Data Dictionary field mappings; key fields include declarant EORI, procedure codes, commodity code (10-digit UK tariff), customs value, and tax lines.
POST the declaration XML to the Customs Declarations API submit endpoint; parse the synchronous HTTP 202 response and extract the Conversation ID for subsequent notification matching.
Poll the Pull Notifications API or configure a callback endpoint to receive asynchronous CDS decision notifications (accept, reject, query) keyed by Conversation ID.
For rejected declarations, parse the FunctionCode and PointerToDocumentSection elements in the error notification to identify and correct the specific field before resubmission.
Known gotchas
CDS uses WCO DMS XML, not JSON; the schema is complex and commodity-code-dependent — use the HMRC Tariff Stop List and CDS Tariff to determine which data groups are mandatory for a given procedure code.
The default API rate limit is 3 requests per second per application; CDS-approved users can request an elevated limit of 8 requests per second through the Developer Hub support process.
HMRC notifications are asynchronous and may arrive minutes to hours after submission; build idempotent notification handlers keyed on Conversation ID to avoid processing duplicates.
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp