Reference

Cancel a queued order

POST /v1/orders/{id}/cancel. Cancel an order while it is queued; its credits are refunded in full.

Generated from the contractsView as Markdown

POST /v1/orders/{id}/cancel

Cancel an order while it is queued; its credits are refunded in full. Later statuses return 409.

Property	Value
Endpoint	`POST https://mydatahub.emailmovers.com/v1/orders/{id}/cancel`
Operation id	`cancelOrder`
Cost	Free (0 credits)
Access	An API key or an OAuth 2.1 token with the scope `orders:write`.
Idempotency-Key	Optional. Makes a retry safe.
Tag	Orders

Request

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`MyDataHub-Version`	header	string	no	The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window.
`Idempotency-Key`	header	string	no	Makes the request safe to retry: the same key returns the stored response. Keys are kept for the life of the organisation.

Example request

curl -X POST "https://mydatahub.emailmovers.com/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/cancel" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY"

Responses

200: The cancelled order.

Headers: RateLimit, RateLimit-Policy.

Member	Type	Always present	Description
`id`	string	yes	Format: an order id: ord_ followed by a 26 character ULID in upper case Crockford base32, such as ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E.
`status`	enum: `queued`, `building`, `verifying`, `ready`, `failed`, `cancelled`	yes	queued, building, verifying, ready; failed if processing failed; cancelled (only while queued).
`name`	string	no
`quote_id`	string	yes	The machine quote the order settled.
`count_id`	string	yes	The count the machine quote was priced from.
`dataset_version`	string	no	The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable.
`field_set`	string	no
`delivery`	array of enum: `api`, `csv`, `google_sheets`	no
`records`	integer (0 or more)	yes
`credits_charged`	number (0 or more)	yes	Credits, to one decimal place: whole at 1 credit a record, fractional only where a rule is (0.1 company-only, 1.8 outright, both proposed).
`credits_remaining`	number (0 or more)	yes	The balance right after this order was charged.
`cost_gbp`	number (0 or more)	yes	The charge in GBP excluding VAT at your plan's rate.
`licence_expires_at`	string (date) or null	yes	When the licence ends; null for outright ownership.
`licence`	`Licence`	yes	Licence terms as data, on every quote, order, records page and receipt. Records stay usable, pushable and re-downloadable free until reuse_until.
`licence.type`	enum: `multi_use_12m`, `outright`	yes	multi_use_12m (12 month multi-use, every plan) or outright (1.8 credits a record, proposed).
`licence.reuse_until`	string (date) or null	yes	Order date plus 12 months; null for outright.
`licence.resale_prohibited`	boolean	yes
`licence.permitted_channels`	array of enum: `email`, `telephone`, `post`	yes	email, telephone and post on standard terms.
`licence.warranty_url`	string (uri)	yes
`licence.terms_version`	string	yes	The version of the Data Licence and Sharing Agreement the licence is under, such as 1.0.
`licence.terms_url`	string (uri)	no	Where that version of the Data Licence and Sharing Agreement is published.
`confirmed_by`	`ConfirmedBy`	yes	Who approved the spend and from which client, recorded in the audit trail and on invoices.
`confirmed_by.method`	enum: `elicitation_form`, `approval_url`, `agent_key`, `app`	yes	elicitation_form (the MCP form), approval_url (the approval page's confirmation_token), agent_key (a pre-authorised agent key within its limits) or app (a person ordering in the app itself, a first-party session; third-party OAuth clients never count).
`confirmed_by.key_id`	string	no	The agent key, for agent_key.
`confirmed_by.user_id`	string	no	The person who confirmed.
`confirmed_by.client_id`	string	no	The OAuth client, such as a Client ID Metadata Document URL.
`confirmed_by.user_agent`	string or null	no	The calling client's User-Agent.
`confirmed_by.mtls_certificate_fingerprint`	string or null	no	SHA-256 of the client certificate when one was presented (ChatGPT's mTLS).
`confirmed_by.web_bot_auth_signature_agent`	string or null	no	The Signature-Agent of a verified Web Bot Auth signature, when present.
`confirmed_by.confirmed_at`	string (date-time)	no
`verification`	object	no	The real-time check at delivery, such as 4,102 checked, 4,071 passed.
`verification.checked`	integer (0 or more)	yes
`verification.passed`	integer (0 or more)	yes
`verification.replaced`	integer (0 or more)	yes
`records_url`	string (uri-reference)	yes	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`download_url`	string (uri-reference)	no	302 to a single-use signed URL that lives 5 minutes.
`receipt_url`	string (uri-reference)	no	A path on https://mydatahub.emailmovers.com starting /v1/. Resolve it against the origin (RFC 3986), not by appending it to the server URL.
`validation_report`	`ValidationReportLinks`	no	Present once the order is ready.
`validation_report.pdf_url`	string (uri)	yes
`validation_report.json_url`	string (uri)	yes
`buyer_kit`	`BuyerKit`	no	Four signed documents that help the buyer use the list lawfully.
`buyer_kit.draft_lia_url`	string (uri)	yes
`buyer_kit.first_email_wording_url`	string (uri)	yes
`buyer_kit.article30_stub_url`	string (uri)	yes
`buyer_kit.due_diligence_file_url`	string (uri)	yes
`created_at`	string (date-time)	no
`ready_at`	string (date-time) or null	no
`failure`	string or null	no

Example response

{
  "id": "ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E",
  "status": "cancelled",
  "credits_charged": 0,
  "records": 5000,
  "confirmed_by": {
    "method": "agent_key",
    "key_id": "key_01JB3Z4Q2V7XN3M9R6T1Y5W8ZA",
    "client_id": "https://claude.ai/oauth/claude-code-client-metadata"
  },
  "records_url": "/v1/orders/ord_01JB4N9S3W2X6Y7Z8A1B2C3D4E/records",
  "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3",
  "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
  "credits_remaining": 6200,
  "cost_gbp": 0,
  "licence_expires_at": "2027-09-26",
  "licence": {
    "type": "multi_use_12m",
    "reuse_until": "2027-09-26",
    "resale_prohibited": true,
    "permitted_channels": ["email", "telephone", "post"],
    "warranty_url": "https://emailmovers.com/trust/warranty",
    "terms_version": "2026-09"
  }
}

Errors

Every error is a problem object with a code and a next_step. Every response carries the RateLimit and RateLimit-Policy headers; see Rate limits.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required).
403	`insufficient-scope`, `confirmation-required`, `business-details-required`, `licence-acceptance-required`, `dpa-acceptance-required`, `agent-budget-exceeded`	The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged.
404	`not-found`	No such object for this organisation.
409	`idempotency-key-reused`, `quote-expired`, `order-not-ready`, `order-not-cancellable`	An Idempotency-Key reused with different parameters, an expired machine quote, or an object in the wrong state.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old.