# Create an order (spends credits)

> create_order: Spends 1 credit per complete UK record against a live machine quote from quote_order, and queues the order.

Source: https://emailmovers.com/mydatahub/docs/reference/mcp/create_order

Spends 1 credit per complete UK record against a live machine quote from quote_order, and queues the order. It needs the quote_id and an idempotency_key to reuse on any retry, so a retry never charges twice; a flag set by a model is never consent. Where the host supports elicitation the user confirms the spend in a form or on mydatahub.emailmovers.com; otherwise an agent key must cover it within its per-order cap and monthly budget. If neither applies nothing is charged: the result is a confirmation-required error with an approval_url to give the user, so keep the quote_id; a short balance returns a top_up_url. Call get_order until the status is ready, then fetch_order_records. Lawful basis is UK GDPR Article 6(1)(f) legitimate interests; email audiences include corporate subscribers only by default (PECR), so sole traders and ordinary partnerships are left out unless the toggle is changed.

| Property | Value |
| --- | --- |
| Tool name | `create_order` |
| Position in tools/list | 14 of 22 |
| Cost | 1 credit per record |
| Scope | `orders:write` |
| Annotations | readOnlyHint false, destructiveHint false, idempotentHint true, openWorldHint false |
| Kind | Write; idempotent, not destructive, closed world |
| REST equivalent | [`POST /v1/orders`](https://emailmovers.com/mydatahub/docs/reference/rest/create-order.md) |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This is what `tools/list` returns from https://mydatahub.emailmovers.com/mcp once v2 launches.

## Input

The schema sets `additionalProperties` to false, so a member that is not listed is refused. There is no confirmation flag: a flag set by a model is never consent. See [Spending safely](https://emailmovers.com/mydatahub/docs/spending-safely.md).

| Member | Type | Required | Description |
| --- | --- | --- | --- |
| `quote_id` | string | yes | A live machine quote from quote_order. Without one nothing is charged. |
| `name` | string | no |  |
| `delivery` | array of enum: `api`, `csv`, `google_sheets` | no | api (fetch records), csv (signed download) and google_sheets. Default api. |
| `confirmation_token` | string | no | The token the approval page on mydatahub.emailmovers.com returns once the signed-in person approves. It is bound to that person (their sub), this spend (the machine quote_id, or the enrichment or push) and an expiry no later than the quote's, and it is redeemable once. |
| `idempotency_key` | string | yes | Any unique string, such as a V4 UUID. Reuse it when retrying the same order so it is never charged twice; a different order needs a new key. |

## Example call

The `params` of a `tools/call` request:

```json
{
  "name": "create_order",
  "arguments": {
    "quote_id": "qte_01JB4M2R6T1Y5W8ZAK8Q2V7XN3",
    "idempotency_key": "6f1c3b2a-9d4e-4f8a-b1c2-7e5d9a0f3c21"
  }
}
```

## Output

The result carries `structuredContent` that matches this schema, and one line of text that leads with the number.

| 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 |  |

## Errors

A failed call returns `isError` true. The text content leads with the sentence a person acts on, then the whole problem as JSON, with `code`, `detail`, `next_step` and `did_you_mean`. A 401 and a step-up 403 are answered at HTTP level so the client can start authorisation. See [Errors](https://emailmovers.com/mydatahub/docs/errors.md).