---
title: "Create an order"
description: "Creates an order for the account."
canonical: "https://docs.printags.com/create-an-order/"
last_updated: "2026-11-16"
---

# Create an order

`POST /v2/accounts/{accountId}/orders`

Creates an order for the account. With `isDraft: true` nothing is produced or debited and the order can be validated later; with a live key a firm order debits the account balance and goes to production. With a test key (`sk_test_`) the order is a test order: nothing is debited and nothing is manufactured. Needs an account with a subscription plan (402 otherwise). To retry safely after a timeout, send an `Idempotency-Key` header: a second call with the same key on the same account returns the order already created, without creating or debiting a second one. Without the header, check with `findOrders` before retrying. A firm order is queued here and processed later: send `Prefer: respond-async` to get 202 Accepted, a `Location` header and a `job` to poll with `getJob` (`Retry-After` says when). Without the header the answer stays 200; a draft answers 200 either way.

## Authentication

An API key as a Bearer token: `Authorization: Bearer <key>`. A `sk_test_` key creates and sees test orders only. Keys and test mode: [overview](/).

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `accountId` | path | string | yes | Unique identifier of the account. You can also use the alias `@me` to target the account authenticated by the token, without having to fetch its id first. |
| `Idempotency-Key` | header | string | no | Optional. A unique key of your choice (8 to 100 characters, a UUID for example) that makes the creation safe to retry. The key is scoped to the account and to the key's mode (test or live): a second call with the same key returns HTTP 200 with the same body (`success`, `orderId`) of the order already created, plus an `Idempotent-Replayed: true` header, and creates and debits nothing. The request is not compared with the first one: the same key with a different body still returns the first order. The key is stored in the order's `metadata` (`mcp_idempotency_key`), shared with the MCP `idempotencyKey`. Without the header, nothing changes. A key shorter than 8 or longer than 100 characters is refused with 400. |
| `Prefer` | header | string | no | `respond-async` (RFC 7240): a firm order answers 202 Accepted with the job to poll, instead of 200. The order, its debit and its processing are the same either way. |

## Request body

Content type: `application/json`, required.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `isDraft` | boolean | no | Indicates if the order is a draft |
| `reference` | string | no | Reference for the order |
| `carrierServiceId` | string | no | ID of the carrier service to use for shipping. Defaults to 'lpf_standard' if not provided. Use a service that supports service points when shipTo contains a servicePoint. |
| `shipTo` | [Address](/schemas/address/) | yes |  |
| `shippingFiles` | array of string (uuid) | no | Optional. Ids of documents to ship with the order, such as a personalised A4 cover letter in PDF: they are printed at the shipping step and go in the same shipment as the cards. Upload each file first with `uploadFile`, on the same account. An unknown id or a file of another account is refused with 404 `FILE_NOT_FOUND`, on a draft as on a firm order, which is then neither created nor debited. `getOrder` returns them in `files`. |
| `items` | array of object | no |  |
| `items[].quantity` | integer | yes | Quantity of the product |
| `items[].productId` | string: `pvccard_white`, `mifare1k_pvccard_white`, `ntag213_pvccard_white`, `ntag216_pvccard_white`, `ntag424_pvccard_white`, `ntag424_woodcard` | yes | Product ID of the product |
| `items[].metadata` | object | no | Additional metadata for the product |
| `items[].packagingId` | string | no | ID of the packaging |
| `items[].printingVisuals` | array of string (uuid), nullable | no | List of printing visuals for the product, obtained from the files API |
| `items[].nfc` | [NFC](/schemas/nfc/) or array of [NFC](/schemas/nfc/) | no |  |

```json
{
  "isDraft": false,
  "reference": "Order-JeanDupont-2024",
  "carrierServiceId": "lpf_standard",
  "shipTo": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Jean Dupont",
    "phone": "+33612345678",
    "email": "jean.dupont@example.fr",
    "address": {
      "addressLine1": "10 rue de la République",
      "addressLine2": "Appartement 123",
      "city": "Paris",
      "postcode": "75001",
      "countryCode": "FR"
    },
    "servicePoint": {
      "id": "12624766",
      "country": "LU"
    }
  },
  "shippingFiles": [
    "3f1c2b7a-5d4e-4f60-9a8b-1c2d3e4f5a6b"
  ],
  "items": [
    {
      "quantity": 10,
      "productId": "ntag424_pvccard_white",
      "metadata": {
        "internalId": "a3d3842e-89c0-41d2-9384-2e89c021d2bc"
      },
      "packagingId": "aluminum_protection",
      "printingVisuals": [
        "0806a77d-8007-4cfc-86a7-7d80079cfc8f",
        "a77d8007-007c-fc86-7a7d-80079cfc8f0"
      ]
    }
  ]
}
```

## Responses

| Status | Description |
| --- | --- |
| 200 | Order created successfully, or, for a replayed `Idempotency-Key`, the order already created (header `Idempotent-Replayed true`) |
| 202 | With `Prefer: respond-async`, a firm order: created, debited and queued; its processing is the job to poll |
| 400 | Bad request, invalid input. `INVALID_QUANTITY` for a quantity that is not a whole number of at least 1 (a missing quantity counts as 1). An `Idempotency-Key` header of fewer than 8 or more than 100 characters is refused (`INVALID_IDEMPOTENCY_KEY`, or a validation error). |
| 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) |
| 402 | The account has no plan (`SUBSCRIPTION_REQUIRED`). Orders, test orders included, need an active plan or its free trial. |
| 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or targets another account (`ACCOUNT_ACCESS_DENIED`, refused once the account guard is enforced); with an OAuth access token: a token of scope `mcp` (`INSUFFICIENT_SCOPE`), a path naming another account or a person no longer a member of it (`ACCOUNT_ACCESS_DENIED`), a real token on the sandbox host (`SANDBOX_REQUIRES_TEST_KEY`) |
| 404 | Account not found, a printing visual that is not a file of the account (`FILE_NOT_FOUND`), or an `orderId` that is not an order of the account (`ORDER_NOT_FOUND`). |
| 429 |  |
| 500 | Internal server error |

### 200 response

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | no |  |
| `orderId` | string | no |  |

```json
{
  "success": true,
  "orderId": "987e6543-e21a-11d4-a789-0242ac120002"
}
```

## Example

```bash
curl -X POST "https://api.printags.com/v2/accounts/@me/orders" \
  -H "Authorization: Bearer $PRINTAGS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"isDraft":false,"reference":"Order-JeanDupont-2024","carrierServiceId":"lpf_standard","shipTo":{"id":"123e4567-e89b-12d3-a456-426614174000","name":"Jean Dupont","phone":"+33612345678","email":"jean.dupont@example.fr","address":{"addressLine1":"10 rue de la République","addressLine2":"Appartement 123","city":"Paris","postcode":"75001","countryCode":"FR"},"servicePoint":{"id":"12624766","country":"LU"}},"shippingFiles":["3f1c2b7a-5d4e-4f60-9a8b-1c2d3e4f5a6b"],"items":[{"quantity":10,"productId":"ntag424_pvccard_white","metadata":{"internalId":"a3d3842e-89c0-41d2-9384-2e89c021d2bc"},"packagingId":"aluminum_protection","printingVisuals":["0806a77d-8007-4cfc-86a7-7d80079cfc8f","a77d8007-007c-fc86-7a7d-80079cfc8f0"]}]}'
```
