# Printags API documentation This is the official API documentation for Printags: PVC, NFC and wood cards, printed and encoded. If you have any questions, please contact us at contact@printags.com. Authentication: send your API key as a Bearer token, `Authorization: Bearer `. Keys are created in the dashboard and act on the account that holds them. Live keys start with `sk_live_`: their orders are real, debited and manufactured. Test keys start with `sk_test_`: their orders are test orders, never debited and never manufactured, and a test key only sees test orders (a live key only sees real ones); use `simulateOrderStatus` to move a test order through its life cycle and receive the same webhooks as in production. Four routes need no key: `listOrderStatuses`, `listShippingCarriers`, `calculateShippingRates` and `getFile`. Errors: a failed call answers with a non-2xx status and the JSON body described by the `Error` schema (`success: false`, a machine-readable `code`, a `message`). Pagination: `listOrders` is the only list that pages (the other lists return everything). Walk it with a cursor: call it with `limit`, then again with `cursor` set to the `pagination.next_cursor` of the page before, until `has_more` is false and `next_cursor` null; `page` and `per_page` (offset) keep working. Long-running work: a firm order is queued, not made, by `createOrder`; send `Prefer: respond-async` to get 202 Accepted with a `Location` to poll (`getJob`), which answers the job's `status` (pending, running, succeeded, failed) and a `Retry-After`. Rate limit: 1200 calls per minute per API key, and 6000 per minute per IP address for the calls without a key; every response of a limited operation carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (the `X-RateLimit-*` forms too), and a 429 `RATE_LIMITED` carries `Retry-After`; the file download (`getFile`) is not limited. Version 2 serves the routes of version 1 under /v2, with the names of the platform: an order's items (version 1 product_groups) and units (version 1 products, the cards), the catalogue's products (version 1 models, productId for modelId) and shipments (version 1 shippings). Version 1 is deprecated since 25 October 2026 and will be removed on 4 January 2027. ## Versioning and deprecation The version is in the path: `/v2` is the current version. A version, or an operation, due for removal says so on every response before it goes: a `Deprecation` header (RFC 9745) with the date the retirement was announced, a `Sunset` header (RFC 8594) with the date it stops answering, and a `Link` to its successor. Both headers are listed under `components.headers` so a client can watch for them. Today they appear on the routes of version 1 only (Deprecation: 25 October 2026, Sunset: 4 January 2027); no version 2 operation is deprecated. ## Authentication with OAuth An application acting for the owners of Printags accounts (a shop plugin, a SaaS) does not ask them for an API key: it asks them, through OAuth 2.1 (authorization code, PKCE S256, `scope=api`), for an access token on ONE of their accounts, and sends it as the key would be, `Authorization: Bearer pta_...`. See the `OAuth2` security scheme for the endpoints and their parameters. ## Test mode Test credentials create test orders, neither debited nor manufactured: a `sk_test_` key, or an OAuth authorization started on the sandbox host (`https://sandbox-api.printags.com/oauth/authorize`, the rest of the flow unchanged). The sandbox host (`https://sandbox-api.printags.com`) refuses any real credential with 403 `SANDBOX_REQUIRES_TEST_KEY`; a test credential also works on `https://api.printags.com`. Move a test order through its life cycle with `simulateOrderStatus`: it sends the same webhooks as in production (`livemode: false`). ## Integrate a shop The path of an e-commerce plugin (WooCommerce, Shopify...) whose customers upload their own visual: 1. **Connect.** Once per shop and per mode, register the application: `POST /oauth/register` with `client_name` (the shop's name) and `redirect_uris` (its https callback). Send the merchant to `/oauth/authorize` (`response_type=code`, `client_id`, `redirect_uri`, `scope=api`, `code_challenge` (S256 of a random verifier), `code_challenge_method=S256`, `state` bound to the merchant's session), on the sandbox host for a test connection. The merchant picks the account to connect (a live connection: only the account's owner or administrators, 403 `ACCOUNT_MANAGER_REQUIRED` otherwise; a test one: any member); the callback receives `code` and `state`: check `state`, then `POST /oauth/token` with `grant_type=authorization_code`, `code`, `code_verifier`, `redirect_uri` and `client_id`. Keep both tokens on the server only; refresh the access token (1 hour) with the refresh token (60 days, renewed on each use). `GET /v2/accounts/@me` shows the account connected and its balance. 2. **Upload from the browser.** Your server calls `createFileUpload` (`POST /v2/accounts/@me/files/uploads` with `fileName` and `contentType`) and hands only `upload.uploadUrl` to the page. The page sends the file itself: `PUT ` with the file as the body and the same `Content-Type`, no Authorization (CORS is open). The answer's `file.fileId` is all you keep. The URL is valid 15 minutes, for one file of 25 MB at most (PNG, JPEG or PDF). 3. **Quote.** Before ordering, `quoteOrder` (`POST /v2/accounts/@me/orders/quote`) with the body you will send to `createOrder`: `totalExclVat`, `balance` and `enoughFunds` say whether the balance covers the order (always true in test mode). Nothing is created or debited. 4. **Order.** `createOrder` (`POST /v2/accounts/@me/orders`) with `isDraft: false`, your order number as `reference`, the customer's `shipTo`, and one item per line (`productId`, `quantity`, `printingVisuals` with the `fileId`). Send an `Idempotency-Key` derived from your own order (e.g. `shop--`, 8 to 100 characters): a retry after a timeout or a 5xx returns the order already created instead of debiting a second one. 5. **Follow with webhooks.** At connection time, `createWebhook` (`POST /v2/accounts/@me/webhooks`) with your endpoint and `events` (`order.updated` for every status change, `order.shipped` for the tracking numbers), and store the `secret`, given only then. On each delivery, verify `X-Printags-Signature: t=,v1=`: compute the HMAC-SHA256 of `.` keyed by the secret, compare it to `v1` in constant time, refuse a `t` more than 5 minutes away, and deduplicate on the body's `id`. Answer 2xx within 10 seconds. Fall back on `getOrder` for an order whose event you missed. 6. **Disconnect.** `POST /oauth/revoke` with the refresh token (or the access token): the authorization, its tokens and the webhook endpoints created with it are removed at once. A merchant who revokes the application from the dashboard has the same effect: the next call answers 401 `INVALID_TOKEN`. ## Servers - `https://api.printags.com`: Main (production) server - `https://sandbox-api.printags.com`: Sandbox: accepts only test API keys (`sk_test_...`) and the access tokens of test OAuth authorizations (started at `https://sandbox-api.printags.com/oauth/authorize`); any other credential (a live key, a dashboard session, a real OAuth token) is refused with a 403 `SANDBOX_REQUIRES_TEST_KEY`. The orders you create are test orders, neither debited nor manufactured. A test credential also works on the production server, where it creates test orders as well. ## Authentication An API key (`sk_live_...` for real orders, `sk_test_...` for test orders), or the JWT of a dashboard session, in the Authorization header: `Authorization: Bearer `. An OAuth access token (`OAuth2`) is accepted wherever a key is. ## Accounts - [Get the authenticated account](/get-the-authenticated-account/): Returns the account the API key belongs to, with its balance and subscription plan. - [Get an account by ID](/get-an-account-by-id/): Returns an account's details. ## Orders - [Find orders by reference or metadata](/find-orders-by-reference-or-metadata/): Searches the account's orders by `reference` or `metadata`, and can limit the fields returned. - [Get an order by ID](/get-an-order-by-id/): Returns an order with its items, units, shipments, status history and prices. - [List the orders of an account](/list-the-orders-of-an-account/): Returns a page of the account's orders, the most recent first (sorted by creation date, not configurable). - [Create an order](/create-an-order/): Creates an order for the account. - [Validate a draft order](/validate-a-draft-order/): Validates a draft order: computes its prices and, with a live key, debits the account and sends it to production. - [Simulate a status change on a test order](/simulate-a-status-change-on-a-test-order/): Test environment only. - [Get the job of a firm order](/get-the-job-of-a-firm-order/): Polls the job that `createOrder` with `Prefer: respond-async` pointed at (its `Location`). - [Quote an order](/quote-an-order/): Prices an order without creating it: the amount `createOrder` would debit for the same body, with the account's balance and whether it is enough. ## Files - [Upload a visual file](/upload-a-visual-file/): Uploads a file (image or PDF) to the account's storage as `multipart/form-data`. - [Get a file by ID](/get-a-file-by-id/): Returns a stored file. - [Get a signed URL to upload a visual](/get-a-signed-url-to-upload-a-visual/): Gives a time-limited URL a browser can send a visual to directly (`uploadFileToSignedUrl`), without your credentials: ask for it from your server, hand `uploadUrl` to the page, and the page `PUT`s… - [Upload a visual to a signed URL](/upload-a-visual-to-a-signed-url/): The `uploadUrl` of `createFileUpload`: send the file's bytes as the body, with its `Content-Type`. ## Statuses - [List order statuses](/list-order-statuses/): Returns every status of the order life cycle (`id` and `name`). ## Shipping - [List carriers for a destination](/list-carriers-for-a-destination/): Returns the carrier services available for a destination, each with its computed price. - [Calculate shipping rates](/calculate-shipping-rates/): Calculates shipping rates for a list of items. ## Products - [List available products](/list-available-products/): Returns the list of product models available, read from the database. ## Webhooks - [List webhook endpoints](/list-webhook-endpoints/): The account's webhook endpoints, with their events and the health of their deliveries. - [Create a webhook endpoint](/create-a-webhook-endpoint/): Subscribes a URL to events. - [Delete a webhook endpoint](/delete-a-webhook-endpoint/): Removes the endpoint: nothing more is delivered to it. ## Schemas - [Error](/schemas/error/): Body of a failed call: `success`, `status`, `code`, `message`. - [Account](/schemas/account/): Fields of the Account object in the Printags API. - [Address](/schemas/address/): Address can be either a standard address or a service point (relay point). - [Customer](/schemas/customer/): Fields of the Customer object in the Printags API. - [Product](/schemas/product/): Fields of the Product object in the Printags API. - [Unit](/schemas/unit/): Fields of the Unit object in the Printags API. - [Item](/schemas/item/): Fields of the Item object in the Printags API. - [SubscriptionPlan](/schemas/subscriptionplan/): Fields of the SubscriptionPlan object in the Printags API. - [Shipment](/schemas/shipment/): Fields of the Shipment object in the Printags API. - [ShippingCarrier](/schemas/shippingcarrier/): A carrier service available for a destination, with its computed price. - [ShippingRate](/schemas/shippingrate/): A carrier service available for a set of items, with its computed price. - [ShippingEnvelope](/schemas/shippingenvelope/): The packaging envelope selected for the items, based on total volume. - [Order](/schemas/order/): Fields of the Order object in the Printags API. - [NFC](/schemas/nfc/): Fields of the NFC object in the Printags API. - [Job](/schemas/job/): The processing of a firm order: queued by `createOrder`, made by the order worker five minutes later (at once for a test order), retried with a backoff of up to 30 minutes; above 100 cards it waits… - [FileUpload](/schemas/fileupload/): Where and how to send the file: one `PUT` of its bytes to `uploadUrl`, with the same `Content-Type`, before `expiresAt`. - [UploadedFile](/schemas/uploadedfile/): The stored file. - [Quote](/schemas/quote/): What the order would debit as a firm order, computed as `createOrder` debits it: the account's plan, its volume tiers, the visual, the NFC encoding and the shipping. - [Webhook](/schemas/webhook/): An endpoint the account's events are delivered to ## Questions ### How do I get a Printags API key? Create an account at dashboard.printags.com/register, then create an API key in the dashboard. No call with sales is needed. ### Is there a sandbox? Yes. A test key (sk_test_) creates test orders that are neither charged nor manufactured, on https://sandbox-api.printags.com or on the production server. A test key only sees test orders. ### What are the rate limits? 1200 calls per minute per API key, and 6000 per minute per IP address for the calls without a key. Responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers, and a 429 RATE_LIMITED carries Retry-After. ### Is there an SDK? Yes, two: the npm package printags, an SDK and a command line for Node.js 18 or later, and the PyPI package printags, an SDK for Python 3.9 or later (pip install printags). Any other language calls the REST API described by the OpenAPI document. ### Can an AI assistant use the API? Yes, through the Printags MCP server at https://mcp.printags.com, with a Printags account (OAuth) or an API key in an Authorization: Bearer header. ## Machine-readable - [OpenAPI document (JSON)](/openapi.json) and [YAML](/openapi.yaml) - [Interactive reference](/reference/), to send test calls from the browser - [llms.txt](/llms.txt) and [llms-full.txt](/llms-full.txt), every page in one Markdown file - [How an agent gets access](https://www.printags.com/auth.md) - [MCP server for integrators](https://www.printags.com/en/mcp-server/) - [Printags app in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6ad9f6c9e7d08191beb4452deac0a5ad) --- # Printags developer portal Print and encode PVC, NFC and wood cards from your own software, shipped white-label to your customers. ## 1. Get an API key Create an account at [dashboard.printags.com/register](https://dashboard.printags.com/register), then create an API key in the dashboard. A test key (`sk_test_...`) creates test orders that are never debited nor manufactured, and only sees test orders. ## 2. First call, in the sandbox ```bash curl https://sandbox-api.printags.com/v2/accounts/@me \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` The sandbox server only accepts test keys. A test key also works on `https://api.printags.com`, where it creates test orders as well. ## 3. Create an order Upload your artwork with [Upload a visual file](/upload-a-visual-file/), then call [Create an order](/create-an-order/). With `isDraft: true` nothing is produced or debited until you validate the draft. Send an `Idempotency-Key` header to retry safely after a timeout. [Simulate a status change on a test order](/simulate-a-status-change-on-a-test-order/) walks a test order through its life cycle and fires the same webhooks as in production. ## Tools - [OpenAPI document](/openapi.json) and the [interactive console](/reference/) - [SDK and command line for Node.js](https://www.printags.com/en/sdk-cli/): the npm package `printags` - [SDK for Python](https://www.printags.com/en/sdk-cli/#python): the PyPI package `printags` (`pip install printags`) - [MCP server for AI assistants](https://www.printags.com/en/mcp-server/) - [Plans and per-card rates](https://www.printags.com/en/rates-and-subscriptions-printags/) ## Versions and limits Version 2 is current. Version 1 is deprecated since 25 October 2026 and will be removed on 4 January 2027; its responses carry Deprecation and Sunset headers. The rate limit is 1200 calls per minute per API key, announced in RateLimit headers. --- # Get the authenticated account `GET /v2/accounts/@me` Returns the account the API key belongs to, with its balance and subscription plan. Call it first: `account.id` is the `accountId` path parameter of every `/v2/accounts/{accountId}/...` endpoint (the alias `@me` also works there). ## Authentication An API key as a Bearer token: `Authorization: Bearer `. A `sk_test_` key creates and sees test orders only. Keys and test mode: [overview](/). ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved account details | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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`) | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `account` | [Account](/schemas/account/) | no | | ```json { "success": true, "account": { "id": "123e4567-e89b-12d3-a456-426614174000", "displayname": "John Doe", "email": "johndoe@example.com", "phone": "+1234567890", "balance": 100.5, "minimal_balance": 0, "minimal_credit": 0, "fiscal_number": "FR12345678901", "subscription_plan": { "id": "987e6543-e21a-11d4-a789-0242ac120002", "displayname": "Basic Plan", "price": 49.99, "shippingLetter": true, "whiteLabel": false }, "options": { "lang": "EN", "payments": { "groupWithSubscription": false } }, "createdAt": "2024-01-01T10:00:00.000Z", "updatedAt": "2024-11-01T12:00:00.000Z", "subscription_plan_source": "stripe" } } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/@me" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Get an account by ID `GET /v2/accounts/{accountId}` Returns an account's details. An API key only reads the account that holds it (use `@me` or its own id). ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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 | ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved account details | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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 | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `account` | [Account](/schemas/account/) | no | | ```json { "success": true, "account": { "id": "123e4567-e89b-12d3-a456-426614174000", "displayname": "John Doe", "email": "johndoe@example.com", "phone": "+1234567890", "balance": 100.5, "minimal_balance": 0, "minimal_credit": 0, "fiscal_number": "FR12345678901", "subscription_plan": { "id": "987e6543-e21a-11d4-a789-0242ac120002", "displayname": "Basic Plan", "price": 49.99, "shippingLetter": true, "whiteLabel": false }, "options": { "lang": "EN", "payments": { "groupWithSubscription": false } }, "createdAt": "2024-01-01T10:00:00.000Z", "updatedAt": "2024-11-01T12:00:00.000Z", "subscription_plan_source": "stripe" } } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/123e4567-e89b-12d3-a456-426614174000" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Find orders by reference or metadata `GET /v2/accounts/{accountId}/orders/find` Searches the account's orders by `reference` or `metadata`, and can limit the fields returned. The response is not paginated. A test key (`sk_test_`) only finds test orders, a live key only real orders. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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 | | `metadata` | query | string | no | Filter orders based on metadata | | `reference` | query | string | no | Filter orders based on reference | | `fields` | query | string | no | Get only wanted fields | ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved orders | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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`) | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `orders` | array of [Order](/schemas/order/) | no | | ```json { "success": true, "orders": [ { "id": "987e6543-e21a-11d4-a789-0242ac120002", "reference": "Order-JeanDupont-2024", "accountId": "123e4567-e89b-12d3-a456-426614174000", "status": "created", "statusHistory": [ {} ], "units": [], "items": [], "shipments": [], "total": 50.99, "files": [ {} ] } ] } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/123e4567-e89b-12d3-a456-426614174000/orders/find" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Get an order by ID `GET /v2/accounts/{accountId}/orders/{orderId}` Returns an order with its items, units, shipments, status history and prices. A test key only sees test orders, a live key only real orders. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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 | | `orderId` | path | string | yes | Unique identifier of the order | ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved order details | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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 | Order not found | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `order` | [Order](/schemas/order/) | no | | ```json { "success": true, "order": { "id": "987e6543-e21a-11d4-a789-0242ac120002", "reference": "Order-JeanDupont-2024", "accountId": "123e4567-e89b-12d3-a456-426614174000", "status": "created", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "jean.dupont@example.fr", "firstname": "Jean", "lastname": "Dupont", "company": "Dupont Entreprises", "accountId": "c10e4fdf-a77d-457c-8fd6-2c0b29214800", "createdAt": "2024-07-01T09:26:55.737Z" }, "shipTo": { "id": "123e4567-e89b-12d3-a456-426614174000", "name": "Jean Dupont", "phone": "+33612345678", "email": "jean.dupont@example.fr" }, "statusHistory": [ { "id": "987e6543-e21a-11d4-a789-0242ac120002", "status": "created", "createdAt": "2024-07-01T09:26:55.737Z" } ], "units": [ {} ], "items": [ {} ], "shipments": [ {} ], "total": 50.99, "files": [ { "id": "3f1c2b7a-5d4e-4f60-9a8b-1c2d3e4f5a6b", "mimeType": "application/pdf", "size": 48213, "filename": "letter.pdf", "createdAt": "2026-11-16T09:26:55.737Z" } ] } } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/123e4567-e89b-12d3-a456-426614174000/orders/987e6543-e21a-11d4-a789-0242ac120002" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # List the orders of an account `GET /v2/accounts/{accountId}/orders` Returns a page of the account's orders, the most recent first (sorted by creation date, not configurable). `page` and `per_page` paginate (defaults 1 and 20); `status` and `search` filter. Each order is a summary: its items, units, customer and recipient, without the prices and shipments of `getOrder`. The `recipient` (name and email of the delivery address) replaces `shipTo`. A test key (`sk_test_`) only lists test orders, a live key only real orders. For the full detail of one order, call `getOrder`. Cursor pagination: every page carries `pagination.next_cursor` and `pagination.has_more`; pass `cursor` (the `next_cursor` of the page before) to get the orders after it, in the same order, without skipping or repeating one when orders are created meanwhile (`page` is then ignored). `limit` sets the page size of both ways (1 to 100). A cursor this API did not give is refused with 400 `INVALID_CURSOR`. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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, or the alias `@me` for the account authenticated by the token. | | `page` | query | string | no | Page number, starting at 1 (default 1). A value that is not a positive whole number is replaced by 1. Declared as a string so that a malformed value is never refused: the route has always accepted it. | | `per_page` | query | string | no | Orders per page (default 20). A value that is not a positive whole number is replaced by 20. The API sets no maximum: ask for pages of 50 at most. Declared as a string so that a malformed value is never refused: the route has always accepted it. | | `status` | query | string | no | Keeps the orders in one of these statuses: one status, or several separated by commas (`draft,in_queue`). Statuses are listed by `GET /orders/statuses`. Do not repeat the parameter. | | `search` | query | string or array of string | no | Free text, 100 characters kept. Send it once: a repeated parameter is accepted but ignored. Matches, without regard to case, a part of the order's reference, of its customer's name, company or email, of its recipient's name or email, or the exact order id. | | `cursor` | query | string | no | Opaque cursor: the `pagination.next_cursor` of the page before. Returns the orders after that one; `page` is ignored. Do not build it yourself: a value this API did not give is refused with 400 `INVALID_CURSOR`. | | `limit` | query | integer | no | Page size, 1 to 100 (default: `per_page`, else 20). Any other value is refused with 400 `INVALID_LIMIT`. | ## Responses | Status | Description | | --- | --- | | 200 | A page of orders | | 400 | `cursor` is not a `next_cursor` of this API (`INVALID_CURSOR`), or `limit` is not 1 to 100 (`INVALID_LIMIT`) | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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`) | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `orders` | array of [Order](/schemas/order/) + object | no | The orders of the page, most recent first. Empty when the page is past the last one. | | `pagination` | object | no | Without `cursor`: `total`, `page`, `per_page`, `limit`, `next_cursor` and `has_more`. With `cursor`: `limit`, `next_cursor` and `has_more`. | | `pagination.total` | integer | no | Number of orders matching the filters, all pages together | | `pagination.page` | integer | no | The page returned | | `pagination.per_page` | integer | no | The page size used | | `pagination.limit` | integer | no | The page size used | | `pagination.next_cursor` | string, nullable | yes | Pass it as `cursor` to get the next page; null on the last page | | `pagination.has_more` | boolean | yes | Whether orders follow this page | ```json { "success": true, "orders": [ { "id": "987e6543-e21a-11d4-a789-0242ac120002", "reference": "Order-JeanDupont-2024", "accountId": "123e4567-e89b-12d3-a456-426614174000", "status": "created", "statusHistory": [], "units": [], "items": [], "shipments": [], "total": 50.99, "files": [], "recipient": { "name": "Jean Dupont", "email": "jean@example.com" } } ], "pagination": { "total": 134, "page": 1, "per_page": 20, "limit": 20, "next_cursor": "WyIyMDI2LTExLTA5VDEwOjAwOjAwLjAwMFoiLCI3YjFlMmE0Yy0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAiXQ", "has_more": true } } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/@me/orders" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # 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 `. 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"]}]}' ``` --- # Upload a visual file `POST /v2/accounts/{accountId}/files` Uploads a file (image or PDF) to the account's storage as `multipart/form-data`. The id of the stored file goes in `printingVisuals` when creating an order, or in `shippingFiles` for a document shipped with the order (a cover letter in PDF, for example). ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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 | ## Request body Content type: `multipart/form-data`, required. | Field | Type | Required | Description | | --- | --- | --- | --- | | `file` | string (binary) | no | The file to upload | ## Responses | Status | Description | | --- | --- | | 201 | File uploaded successfully | | 400 | Bad request, invalid input | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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 | | 429 | | | 500 | Internal server error | ## Example ```bash curl -X POST "https://api.printags.com/v2/accounts/123e4567-e89b-12d3-a456-426614174000/files" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" \ -F "file=@visual.png" ``` --- # Get a file by ID `GET /v2/accounts/{accountId}/files/{fileId}` Returns a stored file. This route does not check the API key. ## Authentication None: this route answers without an API key. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `accountId` | path | string | yes | Unique identifier of the account | | `fileId` | path | string | yes | Unique identifier of the file | ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved file details | | 404 | File not found | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `file` | object | no | | | `file.id` | string | no | | | `file.name` | string | no | | | `file.size` | number | no | | | `file.createdAt` | string (date-time) | no | | ```json { "success": true, "file": { "id": "987e6543-e21a-11d4-a789-0242ac120002", "name": "example.pdf", "size": 1024, "createdAt": "2024-07-01T09:26:55.737Z" } } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/123e4567-e89b-12d3-a456-426614174000/files/987e6543-e21a-11d4-a789-0242ac120002" ``` --- # Validate a draft order `POST /v2/accounts/{accountId}/orders/{orderId}/validate` Validates a draft order: computes its prices and, with a live key, debits the account and sends it to production. The order must be in `draft` status. Test orders debit nothing. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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 | | `orderId` | path | string | yes | Unique identifier of the order | ## Responses | Status | Description | | --- | --- | | 200 | Order validated successfully | | 400 | Bad request, invalid input | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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 | Order not found | | 429 | | | 500 | Internal server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `prices` | object | no | | | `prices.items` | array of object | no | | | `prices.items[].index` | integer | no | | | `prices.items[].quantity` | integer | no | | | `prices.items[].productId` | string | no | | | `prices.items[].unit_charges` | object | no | | | `prices.items[].charges` | object | no | | | `prices.items[].price` | number | no | | | `prices.items[].unit_price` | number | no | | | `prices.shipping` | object | no | | | `prices.shipping.transporter` | string | no | | | `prices.shipping.price` | number | no | | | `prices.total` | number | no | | ```json { "success": true, "prices": { "items": [ { "index": 0, "quantity": 10, "productId": "ntag424_pvccard_white", "unit_charges": { "encoding": 0.5, "product": 0.5, "printing": 0.1, "packaging": 0.2, "recordOptions": 0.3 }, "charges": { "encoding": 5, "product": 5, "printing": 1, "packaging": 2, "recordOptions": 3 }, "price": 4.49, "unit_price": 4.49 } ], "shipping": { "transporter": "default", "price": 5.99 }, "total": 50.99 } } ``` ## Example ```bash curl -X POST "https://api.printags.com/v2/accounts/123e4567-e89b-12d3-a456-426614174000/orders/987e6543-e21a-11d4-a789-0242ac120002/validate" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Simulate a status change on a test order `POST /v2/accounts/{accountId}/orders/{orderId}/simulate` Test environment only. Moves a test order, created with a `sk_test_` key, to the requested status and sends the same webhooks as in production (`order.updated`, plus `order.shipped` or `order.delivered`). Without a printer, this is how you see an order go through its life cycle. Real orders are refused with a 404. A test order is processed within a few seconds of its creation: until then (statuses `creating`, `draft`, `in_queue`) this endpoint answers 409 `TEST_ORDER_NOT_READY`, retry shortly. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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`. | | `orderId` | path | string | yes | Unique identifier of the test order | ## Request body Content type: `application/json`, required. | Field | Type | Required | Description | | --- | --- | --- | --- | | `status` | string | yes | Any status of the order life cycle, see `GET /orders/statuses`. | ```json { "status": "shipped" } ``` ## Responses | Status | Description | | --- | --- | | 200 | Status changed, webhooks sent | | 400 | Missing or unknown status | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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 | Test order not found. Only orders created with a `sk_test_` key can be simulated. | | 409 | The test order is still being processed (`TEST_ORDER_NOT_READY`), retry in a few seconds | | 429 | | | 500 | Internal server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `order` | object | no | The order in its new status | ```json { "success": true } ``` ## Example ```bash curl -X POST "https://api.printags.com/v2/accounts/@me/orders/987e6543-e21a-11d4-a789-0242ac120002/simulate" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"status":"shipped"}' ``` --- # List order statuses `GET /v2/statuses` Returns every status of the order life cycle (`id` and `name`). This route does not need authentication. ## Authentication None: this route answers without an API key. ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved all statuses | | 429 | | | 500 | Server error | ## Example ```bash curl -X GET "https://api.printags.com/v2/statuses" ``` --- # List carriers for a destination `GET /v2/shipping/carriers` Returns the carrier services available for a destination, each with its computed price. Useful to let a customer pick a carrierServiceId before creating an order. Only services whose price is greater than 0 for the requested destination are returned. ## Authentication None: this route answers without an API key. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `to_country` | query | string | yes | ISO 2-letter destination country code. | | `to_postal_code` | query | string | no | Destination postal code (reserved for postal-code-aware pricing). | | `weight` | query | integer | no | Total weight in grams. When provided, only services whose weight range covers it are returned. | ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved available carriers | | 400 | Bad request, missing required parameter (e.g. to_country) | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `count` | integer | no | | | `carriers` | array of [ShippingCarrier](/schemas/shippingcarrier/) | no | | ```json { "success": true, "count": 2, "carriers": [ { "id": "lpf_standard", "name": "La Poste - Lettre Suivie", "code": "laposte", "hasServicePoints": false, "apiProvider": "laposte", "countries": [ "FR", "BE" ], "enabledCountries": [ "FR", "BE", "LU" ], "price": 2.3, "weightTier": 0, "priceTiers": { "0": 2.3, "250": 3 }, "minWeight": 0, "maxWeight": 3000 } ] } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/shipping/carriers?to_country=FR" ``` --- # Calculate shipping rates `POST /v2/shipping/rates` Calculates shipping rates for a list of items. The endpoint computes the total weight and volume of the items (model and optional packaging), selects the appropriate envelope, and returns the carrier services available for the destination with their price. Only services whose price is greater than 0 are returned. To the United Kingdom (GB), the Sendcloud services (Colissimo International…) are not returned: the carrier refuses their label without the sender's UK VAT and EORI numbers, and order creation refuses them (GB_CUSTOMS_NUMBERS_REQUIRED). Use lpf_international to GB. The route stays public; an optional Bearer API key names the account. ## Authentication None: this route answers without an API key. ## Request body Content type: `application/json`, required. | Field | Type | Required | Description | | --- | --- | --- | --- | | `to_country` | string | yes | ISO 2-letter destination country code. | | `to_postal_code` | string | no | Destination postal code (reserved for postal-code-aware pricing). | | `items` | array of object | yes | Items to ship. Weight and volume are derived from each model (and optional packaging). | | `items[].productId` | string: `pvccard_white`, `mifare1k_pvccard_white`, `ntag213_pvccard_white`, `ntag216_pvccard_white`, `ntag424_pvccard_white`, `ntag424_woodcard` | yes | Product ID of the item. | | `items[].packagingId` | string, nullable | no | Optional packaging ID, added to the item weight and volume. | | `items[].quantity` | integer | no | Number of units for this item. | ```json { "to_country": "FR", "to_postal_code": "75001", "items": [ { "productId": "ntag424_pvccard_white", "packagingId": "aluminum_protection", "quantity": 10 } ] } ``` ## Responses | Status | Description | | --- | --- | | 200 | Successfully calculated shipping rates | | 400 | Bad request, missing to_country or items | | 404 | No matching models found for the provided items | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `weight` | integer | no | Total shipping weight in grams (items + envelope). | | `volume` | number | no | Total items volume in cm³. | | `envelope` | [ShippingEnvelope](/schemas/shippingenvelope/) | no | | | `count` | integer | no | | | `carriers` | array of [ShippingRate](/schemas/shippingrate/) | no | | ```json { "success": true, "weight": 110, "volume": 42.5, "envelope": { "id": "custom", "name": "Emballage spécial", "weight": 50 }, "count": 2, "carriers": [ { "id": "lpf_standard", "name": "La Poste - Lettre Suivie", "code": "laposte", "serviceCode": "chrono_18", "hasServicePoints": false, "price": 3, "weightTier": 250 } ] } ``` ## Example ```bash curl -X POST "https://api.printags.com/v2/shipping/rates" \ -H "Content-Type: application/json" \ -d '{"to_country":"FR","to_postal_code":"75001","items":[{"productId":"ntag424_pvccard_white","packagingId":"aluminum_protection","quantity":10}]}' ``` --- # List available products `GET /v2/products` Returns the list of product models available, read from the database. This is the authoritative source for the `productId` values used when creating an order or calculating shipping rates. With `include=prices`, each model also carries `price`: what one printed card of it costs the authenticated account under its plan, excluding VAT and shipping (null when the plan does not price that model, or the account has no plan usable by this caller). It is priced as this caller's orders are, so a shop integration can use it as the product's cost; an order of several cards can fall into a cheaper tier of the plan, and its exact amount is given by the order quote. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. A `sk_test_` key creates and sees test orders only. Keys and test mode: [overview](/). ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `include` | query | string: `prices` | no | `prices` adds the account's price of one printed card to each model. | ## Responses | Status | Description | | --- | --- | | 200 | Successfully retrieved available models | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 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`) | | 429 | | | 500 | Server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `models` | array of [Product](/schemas/product/) | no | | ```json { "success": true, "models": [ { "id": "ntag424_pvccard_white", "size": { "width": 0, "height": 0, "length": 0, "weight": 6 }, "prices": [], "canBeEncoded": true, "price": { "currency": "eur", "quantity": 1, "unitPriceExclVat": 2.1 } } ] } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/products" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Get the job of a firm order `GET /v2/accounts/{accountId}/jobs/{jobId}` Polls the job that `createOrder` with `Prefer: respond-async` pointed at (its `Location`). `status` is `pending` or `running` while the order is processed (poll again after `Retry-After` seconds), then `succeeded` with `result` (the order to read with `getOrder`) or `failed` with `error`. A job is only readable by the account that created its order, and in its key's mode (test or live). ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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, or the alias `@me` for the account authenticated by the token. | | `jobId` | path | string (uuid) | yes | The `job.id` of the 202 answer | ## Responses | Status | Description | | --- | --- | | 200 | The job | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`); 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 | No job of this id for the authenticated account and mode (`JOB_NOT_FOUND`) | | 500 | Internal server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `job` | [Job](/schemas/job/) | no | | ```json { "success": true, "job": { "id": "0b6f1c9e-3c1a-4e57-9f5e-6a2d8f1b7c40", "type": "order.treatment", "status": "pending", "stage": "queued", "orderId": "7b1e2a4c-0000-4000-8000-000000000000", "location": "/v2/accounts/@me/jobs/0b6f1c9e-3c1a-4e57-9f5e-6a2d8f1b7c40", "retryAfter": 300, "result": { "orderStatus": "validated", "location": "/v2/accounts/@me/orders/7b1e2a4c-0000-4000-8000-000000000000" }, "error": { "code": "ORDER_PROCESSING_FAILED" } } } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/@me/jobs/{jobId}" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Get a signed URL to upload a visual `POST /v2/accounts/{accountId}/files/uploads` Gives a time-limited URL a browser can send a visual to directly (`uploadFileToSignedUrl`), without your credentials: ask for it from your server, hand `uploadUrl` to the page, and the page `PUT`s the file there. PNG, JPEG or PDF, 25 MB at most. The URL is valid 15 minutes, for one file, on this account and in the key's mode. The file it yields is the one `POST /v2/accounts/{accountId}/files` would store. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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, or the alias `@me` for the account authenticated by the token. An API key or an OAuth token acts on its own account only: another account's id is refused with 403 `ACCOUNT_ACCESS_DENIED`. | ## Request body Content type: `application/json`, required. | Field | Type | Required | Description | | --- | --- | --- | --- | | `fileName` | string | yes | Kept as the file's name (path parts removed) | | `contentType` | string: `image/png`, `image/jpeg`, `application/pdf` | yes | | ```json { "fileName": "recto.png", "contentType": "image/png" } ``` ## Responses | Status | Description | | --- | --- | | 201 | The upload URL | | 400 | `fileName` or `contentType` missing (`MISSING_PARAMETERS`), or a type other than PNG, JPEG or PDF (`UNSUPPORTED_FILE_TYPE`) | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or the path names another account (`ACCOUNT_ACCESS_DENIED`); 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`) | | 500 | Internal server error | ### 201 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `upload` | [FileUpload](/schemas/fileupload/) | no | | ```json { "success": true, "upload": { "uploadUrl": "https://api.printags.com/v2/uploads/eyJhIjoiN2IxZTJhNGMifQ.c2lnbmF0dXJl", "method": "PUT", "contentType": "image/png", "maxBytes": 26214400, "expiresAt": "2026-11-10T13:15:00.000Z" } } ``` ## Example ```bash curl -X POST "https://api.printags.com/v2/accounts/@me/files/uploads" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"fileName":"recto.png","contentType":"image/png"}' ``` --- # Upload a visual to a signed URL `PUT /v2/uploads/{token}` The `uploadUrl` of `createFileUpload`: send the file's bytes as the body, with its `Content-Type`. No Authorization header: the token stands in for it. Callable from a browser on any origin (CORS, with its preflight). The content must match the type announced when the URL was made. Limited per IP address (`RATE_LIMITED`, with `Retry-After`). ## Authentication None: this route answers without an API key. ## Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `token` | path | string | yes | The signed token, as `uploadUrl` holds it | ## Request body Content type: `image/png`, required. ## Responses | Status | Description | | --- | --- | | 201 | The file is stored | | 400 | Empty body (`EMPTY_BODY`), or content that is not the announced type (`CONTENT_TYPE_MISMATCH`) | | 401 | Forged or expired token, or one made for another use (`INVALID_UPLOAD_TOKEN`) | | 403 | A live URL used on the sandbox host (`SANDBOX_REQUIRES_TEST_KEY`) | | 409 | The URL already stored its file (`UPLOAD_LINK_USED`): ask for a new one | | 413 | Over 25 MB (`FILE_TOO_LARGE`) | | 422 | A PDF that cannot be prepared for print (`INVALID_FILE`) | | 429 | Too many uploads from this address (`RATE_LIMITED`) | | 500 | Internal server error (`UPLOAD_FAILED`) | ### 201 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `file` | [UploadedFile](/schemas/uploadedfile/) | no | | ```json { "success": true, "file": { "fileId": "f0000000-0000-4000-8000-000000000009", "name": "recto.png", "size": 182044, "contentType": "image/png" } } ``` ## Example ```bash curl -X PUT "https://api.printags.com/v2/uploads/{token}" ``` --- # Quote an order `POST /v2/accounts/{accountId}/orders/quote` Prices an order without creating it: the amount `createOrder` would debit for the same body, with the account's balance and whether it is enough. Send the body you would send to `createOrder`: the country is read from `countryCode`, else `shipTo.address.countryCode`, else `shipTo.servicePoint.country`; the rest of `shipTo`, `reference` and `metadata` are not read, and only the presence of `printingVisuals` counts. Nothing is created or debited. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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, or the alias `@me` for the account authenticated by the token. An API key or an OAuth token acts on its own account only: another account's id is refused with 403 `ACCOUNT_ACCESS_DENIED`. | ## Request body Content type: `application/json`, required. | Field | Type | Required | Description | | --- | --- | --- | --- | | `countryCode` | string | no | Delivery country (ISO 3166-1 alpha-2), instead of `shipTo` | | `shipTo` | object | no | As in `createOrder`: only its country is read | | `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. | | `items` | array of object | yes | | | `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 { "countryCode": "FR", "carrierServiceId": "lpf_standard", "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 | The quote | | 400 | No country (`MISSING_COUNTRY_CODE`), an invalid line (`INVALID_PARAMETERS`, `INVALID_QUANTITY`), an unknown product (`UNKNOWN_PRODUCT`), or a carrier service that does not serve the parcel or the country (`CARRIER_SERVICE_NOT_AVAILABLE`) | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 402 | The account has no plan, so no price (`SUBSCRIPTION_REQUIRED`) | | 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or the path names another account (`ACCOUNT_ACCESS_DENIED`); 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`) | | 500 | Internal server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `quote` | [Quote](/schemas/quote/) | no | | ```json { "success": true, "quote": { "currency": "eur", "mode": "production", "totalExclVat": 42.5, "shippingExclVat": 2.5, "lines": [ { "modelId": "ntag213_pvccard_white", "quantity": 50, "unitPriceExclVat": 0.8, "lineTotalExclVat": 40, "unitCharges": { "model": 0.5, "printing": 0.3 } } ], "balance": 30, "enoughFunds": true } } ``` ## Example ```bash curl -X POST "https://api.printags.com/v2/accounts/@me/orders/quote" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"countryCode":"FR","carrierServiceId":"lpf_standard","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"]}]}' ``` --- # List webhook endpoints `GET /v2/accounts/{accountId}/webhooks` The account's webhook endpoints, with their events and the health of their deliveries. A test credential (key or OAuth token) sees the endpoints made with a test credential, a live one the others. An OAuth token sees only the endpoints it created itself. Events, delivered as a JSON `POST` to the endpoint: `order.created` (an order is created, a firm order once processed), `order.updated` (every status change of an order: `data.status` is the new status, e.g. `in_queue`, `manufacturing`, `shipped`, `delivered`, `cancelled`) and `order.shipped` (the order left: `data.shippings[].trackingNumber` carries the tracking number; sent again when a new label gives a new number). `order.encoded` is accepted in `events` but not sent today. The body: `{ id, created, event, livemode, data }`, `id` the event's id (the same for every endpoint and every retry: deduplicate on it), `created` its epoch seconds, `data` the order as `getOrder` returns it in version 1. Headers: `X-Printags-Event` (the event), `X-Printags-Delivery` (the delivery's id) and `X-Printags-Signature: t=,v1=`, where `v1` is the HMAC-SHA256, keyed by the endpoint's `secret` (`whsec_...`), of `.`: recompute it on the raw bytes, compare in constant time and refuse a `t` more than 5 minutes old. Answer 2xx within 10 seconds; anything else is retried with a backoff, up to 15 attempts. An endpoint created with a test credential (a `sk_test_` key, a test OAuth token) receives test orders' events only (`livemode` false); any other endpoint receives the events of both, told apart by `livemode`. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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, or the alias `@me` for the account authenticated by the token. An API key or an OAuth token acts on its own account only: another account's id is refused with 403 `ACCOUNT_ACCESS_DENIED`. | ## Responses | Status | Description | | --- | --- | | 200 | The endpoints | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or the path names another account (`ACCOUNT_ACCESS_DENIED`); 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`) | | 500 | Internal server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `webhooks` | array of [Webhook](/schemas/webhook/) | no | | ```json { "success": true, "webhooks": [ { "id": "3c0e8f8a-0000-4000-8000-000000000001", "endpoint": "https://boutique.example/wp-json/printags/v1/webhook", "description": "WooCommerce", "webhook_events": [ {} ] } ] } ``` ## Example ```bash curl -X GET "https://api.printags.com/v2/accounts/@me/webhooks" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Create a webhook endpoint `POST /v2/accounts/{accountId}/webhooks` Subscribes a URL to events. The answer holds the signing `secret`, given this once only: store it. The URL must be public (http or https, 255 characters at most); at most 25 endpoints per account. An endpoint created with an OAuth token is removed when that authorization is revoked. Events, delivered as a JSON `POST` to the endpoint: `order.created` (an order is created, a firm order once processed), `order.updated` (every status change of an order: `data.status` is the new status, e.g. `in_queue`, `manufacturing`, `shipped`, `delivered`, `cancelled`) and `order.shipped` (the order left: `data.shippings[].trackingNumber` carries the tracking number; sent again when a new label gives a new number). `order.encoded` is accepted in `events` but not sent today. The body: `{ id, created, event, livemode, data }`, `id` the event's id (the same for every endpoint and every retry: deduplicate on it), `created` its epoch seconds, `data` the order as `getOrder` returns it in version 1. Headers: `X-Printags-Event` (the event), `X-Printags-Delivery` (the delivery's id) and `X-Printags-Signature: t=,v1=`, where `v1` is the HMAC-SHA256, keyed by the endpoint's `secret` (`whsec_...`), of `.`: recompute it on the raw bytes, compare in constant time and refuse a `t` more than 5 minutes old. Answer 2xx within 10 seconds; anything else is retried with a backoff, up to 15 attempts. An endpoint created with a test credential (a `sk_test_` key, a test OAuth token) receives test orders' events only (`livemode` false); any other endpoint receives the events of both, told apart by `livemode`. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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, or the alias `@me` for the account authenticated by the token. An API key or an OAuth token acts on its own account only: another account's id is refused with 403 `ACCOUNT_ACCESS_DENIED`. | ## Request body Content type: `application/json`, required. | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string (uri) | yes | | | `events` | array of string | yes | | | `description` | string, nullable | no | | ```json { "url": "https://boutique.example/wp-json/printags/v1/webhook", "events": [ "order.updated", "order.shipped" ], "description": "WooCommerce" } ``` ## Responses | Status | Description | | --- | --- | | 200 | The endpoint, and its signing secret | | 400 | `url` or `events` missing (`MISSING_PARAMETERS`), a URL that is not public (`INVALID_WEBHOOK_URL`), a bad list (`INVALID_PARAMETERS`), or an event name that does not exist (`UNKNOWN_WEBHOOK_EVENTS`, with `unknown_events`) | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or the path names another account (`ACCOUNT_ACCESS_DENIED`); 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`) | | 409 | The account already holds 25 endpoints (`WEBHOOK_LIMIT_REACHED`) | | 500 | Internal server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `secret` | string | no | The HMAC key of `X-Printags-Signature`, given only here | | `webhook` | [Webhook](/schemas/webhook/) | no | | ```json { "success": true, "secret": "whsec_0f3c...", "webhook": { "id": "3c0e8f8a-0000-4000-8000-000000000001", "endpoint": "https://boutique.example/wp-json/printags/v1/webhook", "description": "WooCommerce", "webhook_events": [ { "name": "order.shipped" } ] } } ``` ## Example ```bash curl -X POST "https://api.printags.com/v2/accounts/@me/webhooks" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://boutique.example/wp-json/printags/v1/webhook","events":["order.updated","order.shipped"],"description":"WooCommerce"}' ``` --- # Delete a webhook endpoint `DELETE /v2/accounts/{accountId}/webhooks/{webhookId}` Removes the endpoint: nothing more is delivered to it. A key deletes the endpoints of its own account and mode only; an OAuth token, only the endpoints it created itself. ## Authentication An API key as a Bearer token: `Authorization: Bearer `. 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, or the alias `@me` for the account authenticated by the token. An API key or an OAuth token acts on its own account only: another account's id is refused with 403 `ACCOUNT_ACCESS_DENIED`. | | `webhookId` | path | string (uuid) | yes | The endpoint's `id` | ## Responses | Status | Description | | --- | --- | | 200 | The deleted endpoint | | 401 | Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`) | | 403 | The API key is inactive or revoked (`INACTIVE_API_KEY`), or the path names another account (`ACCOUNT_ACCESS_DENIED`); 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 | No endpoint of this id for the account and mode (`WEBHOOK_NOT_FOUND`) | | 500 | Internal server error | ### 200 response | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | no | | | `webhook` | [Webhook](/schemas/webhook/) | no | | ```json { "success": true, "webhook": { "id": "3c0e8f8a-0000-4000-8000-000000000001", "endpoint": "https://boutique.example/wp-json/printags/v1/webhook", "description": "WooCommerce", "webhook_events": [ { "name": "order.shipped" } ] } } ``` ## Example ```bash curl -X DELETE "https://api.printags.com/v2/accounts/@me/webhooks/{webhookId}" \ -H "Authorization: Bearer $PRINTAGS_API_KEY" ``` --- # Error Body of a failed call: `success`, `status`, `code`, `message`. The request validator (an invalid body or parameter) and the unexpected errors also nest `code` and `message` in `error`, and the validator lists its findings in `errors`, one per invalid field; a few endpoint errors (`MISSING_COUNTRY_CODE`, `INVALID_IDEMPOTENCY_KEY`) only carry the nested `error`. Read `code` rather than `message`: messages may be French or English and can change. | Field | Type | Required | Description | | --- | --- | --- | --- | | `success` | boolean | yes | | | `status` | integer | no | HTTP status, repeated in the body | | `code` | string | no | Machine-readable code, e.g. `VALIDATION_ERROR` (400: a field of the body, query or path breaks its rule, such as a comma in a city or an address line over 38 characters; `errors` names the field), `NO_TOKEN` (401: no Authorization header), `INVALID_AUTH_FORMAT`, `INVALID_API_KEY`, `INACTIVE_API_KEY`, `ACCOUNT_ACCESS_DENIED`, `SUBSCRIPTION_REQUIRED`, `INSUFFICIENT_FUNDS`, `ORDER_NOT_FOUND`, `FILE_NOT_FOUND`, `MISSING_TO_COUNTRY`, `TEST_ORDER_NOT_READY`, `RATE_LIMITED`, `SANDBOX_REQUIRES_TEST_KEY`, `INTERNAL_ERROR` (500), and with an OAuth access token `INVALID_TOKEN` (401), `INSUFFICIENT_SCOPE` (403: a token of scope `mcp` on this API), `ACCOUNT_ACCESS_DENIED` (403) and `SANDBOX_REQUIRES_TEST_KEY` (403) | | `message` | string | no | | | `inputs` | object | no | The values the error is about, when the endpoint gives them | | `error` | object | no | Nested form of `code` and `message`, used by validation errors and unexpected errors | | `error.code` | string | no | | | `error.message` | string | no | | | `errors` | array of object | no | Validation findings (request validator): one entry per invalid field, `path` naming it | | `errors[].path` | string | no | | | `errors[].message` | string | no | | | `errors[].errorCode` | string | no | | ## Example ```json { "success": false, "status": 404, "code": "ORDER_NOT_FOUND", "message": "Order 987e6543-e21a-11d4-a789-0242ac120002 not found", "error": { "code": "VALIDATION_ERROR" }, "errors": [ { "path": "/body/shipTo/address/city" } ] } ``` --- # Account The `Account` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | | | `displayname` | string | no | | | `email` | string (email) | no | | | `phone` | string | no | | | `balance` | number (float) | no | | | `minimal_balance` | number | no | | | `minimal_credit` | number | no | | | `fiscal_number` | string | no | | | `subscription_plan` | [SubscriptionPlan](/schemas/subscriptionplan/) | no | | | `options` | object | no | | | `options.lang` | string | no | | | `options.payments` | object | no | | | `options.payments.groupWithSubscription` | boolean | no | | | `createdAt` | string (date-time) | no | | | `updatedAt` | string (date-time) | no | | | `subscription_plan_source` | string: `stripe`, `manual`, `shopify`, `woocommerce` | no | Who bills the account's plan: `stripe` (a Printags subscription paid by card), `manual` (given by the Printags team), `shopify` or `woocommerce` (billed by the platform; Stripe Checkout then answers 409 `PLAN_BILLED_BY_PLATFORM`). Absent when the account has no plan, or for an older plan whose source is not recorded yet (resolved at its next subscription change). It cannot be changed through the API. | ## Example ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "displayname": "John Doe", "email": "johndoe@example.com", "phone": "+1234567890", "balance": 100.5, "minimal_balance": 0, "minimal_credit": 0, "fiscal_number": "FR12345678901", "subscription_plan": { "id": "987e6543-e21a-11d4-a789-0242ac120002", "displayname": "Basic Plan", "price": 49.99, "shippingLetter": true, "whiteLabel": false }, "options": { "lang": "EN", "payments": { "groupWithSubscription": false } }, "createdAt": "2024-01-01T10:00:00.000Z", "updatedAt": "2024-11-01T12:00:00.000Z", "subscription_plan_source": "stripe" } ``` --- # Address Address can be either a standard address or a service point (relay point). Use 'address' for home delivery or 'servicePoint' for relay point delivery. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string, nullable | no | | | `name` | string | yes | | | `phone` | string | yes | | | `email` | string (email) | yes | | | `address` | object | no | Standard address for home delivery. Required if servicePoint is not provided. | | `address.addressLine1` | string | yes | | | `address.addressLine2` | string, nullable | no | | | `address.city` | string | yes | | | `address.postcode` | string | yes | | | `address.countryCode` | string | yes | | | `servicePoint` | object | no | Service point (relay point) for pickup delivery. Required if address is not provided. Use with a carrierServiceId that supports service points. | | `servicePoint.id` | string | yes | The service point ID from the carrier (e.g., Sendcloud service point ID) | | `servicePoint.country` | string | yes | ISO 2-letter country code of the service point | ## Example ```json { "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" } } ``` --- # Customer The `Customer` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | | | `email` | string (email) | no | | | `firstname` | string | no | | | `lastname` | string | no | | | `company` | string | no | | | `accountId` | string | no | The accountId of the owner of this customer | | `createdAt` | string (date-time) | no | | ## Example ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "jean.dupont@example.fr", "firstname": "Jean", "lastname": "Dupont", "company": "Dupont Entreprises", "accountId": "c10e4fdf-a77d-457c-8fd6-2c0b29214800", "createdAt": "2024-07-01T09:26:55.737Z" } ``` --- # Product The `Product` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | Product identifier, used as productId when creating an order. The authoritative list is returned by GET /v2/products; the values below are common examples and may evolve. | | `size` | object | no | | | `size.width` | number | no | | | `size.height` | number | no | | | `size.length` | number | no | | | `size.weight` | number | no | | | `prices` | array of object | no | Pricing entries associated with the model. | | `canBeEncoded` | boolean | no | | | `price` | object, nullable | no | Only with `include=prices`: the price of one printed card for the authenticated account (its plan), excluding VAT and shipping. Null when the plan does not price this model or the account has no plan. | | `price.currency` | string | no | | | `price.quantity` | integer | no | | | `price.unitPriceExclVat` | number | no | | | `price.unitCharges` | object | no | | | `price.unitCharges.product` | number | no | | | `price.unitCharges.printing` | number | no | | ## Example ```json { "id": "ntag424_pvccard_white", "size": { "width": 0, "height": 0, "length": 0, "weight": 6 }, "prices": [], "canBeEncoded": true, "price": { "currency": "eur", "quantity": 1, "unitPriceExclVat": 2.1, "unitCharges": { "product": 1.7, "printing": 0.4 } } } ``` --- # Unit The `Unit` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | | | `product` | [Product](/schemas/product/) | no | | | `metadata` | array of object | no | Always empty, kept for compatibility (the card metadata stopped in June 2024) | | `files` | array of object | no | The files of the card's order item, its front and back visuals | | `status` | string | no | Current status of the product | | `shipments` | array of object | no | Shipping information associated with the product | | `createdAt` | string (date-time) | no | | ## Example ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "product": { "id": "ntag424_pvccard_white", "size": { "width": 0, "height": 0, "length": 0, "weight": 6 }, "prices": [], "canBeEncoded": true, "price": { "currency": "eur", "quantity": 1, "unitPriceExclVat": 2.1, "unitCharges": { "product": 1.7, "printing": 0.4 } } }, "metadata": [], "files": [], "status": "created", "shipments": [], "createdAt": "2024-04-08T13:22:37.000Z" } ``` --- # Item The `Item` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | | | `productId` | string | no | | | `name` | string | no | | | `quantity` | integer | no | | | `nfc` | [NFC](/schemas/nfc/) | no | | | `product` | [Product](/schemas/product/) | no | | ## Example ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "productId": "ntag424_pvccard_white", "name": "Jean Dupont", "quantity": 10, "nfc": { "type": "empty", "content": "https://example.com", "dynamic": { "baseUrl": "https://example.com", "records": { "recordId": 1, "publicKey": "B5ADF942C642D16B2803CA672F47D11D", "privateKey": "82F87EB3F693B84BCC154A0373363A62" } }, "options": { "lock": true, "uid": false } }, "product": { "id": "ntag424_pvccard_white", "size": { "width": 0, "height": 0, "length": 0, "weight": 6 }, "prices": [], "canBeEncoded": true, "price": { "currency": "eur", "quantity": 1, "unitPriceExclVat": 2.1, "unitCharges": { "product": 1.7, "printing": 0.4 } } } } ``` --- # SubscriptionPlan The `SubscriptionPlan` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | | | `displayname` | string | no | | | `price` | number | no | | | `shippingLetter` | boolean | no | | | `whiteLabel` | boolean | no | | ## Example ```json { "id": "987e6543-e21a-11d4-a789-0242ac120002", "displayname": "Basic Plan", "price": 49.99, "shippingLetter": true, "whiteLabel": false } ``` --- # Shipment The `Shipment` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | | | `trackerId` | string | no | | | `trackingNumber` | string | no | | | `unitsByProduct` | object | no | The shipment's units counted per catalogue product, keyed by the product's id | ## Example ```json { "id": "123e4567-e89b-12d3-a456-426614174000", "trackerId": "1234567890", "trackingNumber": "1Z999AA10123456784", "unitsByProduct": { "ntag424_pvccard_white": 4 } } ``` --- # ShippingCarrier A carrier service available for a destination, with its computed price. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | Carrier service identifier to pass as carrierServiceId when creating an order. | | `name` | string | no | Human-readable carrier service name. | | `code` | string | no | Internal carrier code. | | `hasServicePoints` | boolean | no | Whether this service delivers to service points (relay points / lockers). | | `apiProvider` | string | no | Backend provider handling this carrier. | | `countries` | array of string | no | | | `enabledCountries` | array of string | no | Destination countries this service is enabled for ('*' means all). | | `price` | number (float) | no | Price for the requested destination and weight, in EUR. Only services with a price greater than 0 are returned. | | `weightTier` | integer, nullable | no | Weight threshold (in grams) of the matched price tier. | | `priceTiers` | object | no | Raw price tiers for this service. For weight-based providers the keys are weight thresholds in grams; for Sendcloud-based providers the keys are country codes. | | `minWeight` | integer | no | Minimum supported weight in grams. | | `maxWeight` | integer | no | Maximum supported weight in grams. | ## Example ```json { "id": "lpf_standard", "name": "La Poste - Lettre Suivie", "code": "laposte", "hasServicePoints": false, "apiProvider": "laposte", "countries": [ "FR", "BE" ], "enabledCountries": [ "FR", "BE", "LU" ], "price": 2.3, "weightTier": 0, "priceTiers": { "0": 2.3, "250": 3 }, "minWeight": 0, "maxWeight": 3000 } ``` --- # ShippingRate A carrier service available for a set of items, with its computed price. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | Carrier service identifier to pass as carrierServiceId when creating an order. | | `name` | string | no | | | `code` | string | no | | | `serviceCode` | string, nullable | no | Stable code of the service within its carrier (for example chrono_13, chrono_18). Use it to pick a service without parsing its name, which is generated from the carrier catalogue. | | `hasServicePoints` | boolean | no | | | `price` | number (float) | no | Price for the computed weight and destination, in EUR. | | `weightTier` | integer, nullable | no | Weight threshold (in grams) of the matched price tier. | ## Example ```json { "id": "lpf_standard", "name": "La Poste - Lettre Suivie", "code": "laposte", "serviceCode": "chrono_18", "hasServicePoints": false, "price": 3, "weightTier": 250 } ``` --- # ShippingEnvelope The packaging envelope selected for the items, based on total volume. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | no | Envelope identifier, or 'custom' when no standard envelope matches the volume. | | `name` | string | no | | | `weight` | number | no | Envelope weight in grams, included in the total shipping weight. | ## Example ```json { "id": "custom", "name": "Emballage spécial", "weight": 50 } ``` --- # Order The `Order` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string (uuid) | no | | | `reference` | string | no | | | `accountId` | string | no | | | `status` | string | no | | | `customer` | [Customer](/schemas/customer/) | no | | | `shipTo` | [Address](/schemas/address/) | no | | | `statusHistory` | array of object | no | | | `statusHistory[].id` | string (uuid) | no | | | `statusHistory[].status` | string | no | | | `statusHistory[].createdAt` | string (date-time) | no | | | `units` | array of [Unit](/schemas/unit/) | no | | | `items` | array of [Item](/schemas/item/) | no | | | `metadata` | object, nullable | no | Additional metadata for the order | | `shipments` | array of [Shipment](/schemas/shipment/) | no | Shipping information associated with the order | | `total` | number | no | | | `files` | array of object | no | The documents shipped with the order (`shippingFiles` of `createOrder`). Returned by `getOrder` only. | | `files[].id` | string (uuid) | no | | | `files[].mimeType` | string | no | | | `files[].size` | integer | no | Size in bytes | | `files[].filename` | string | no | | | `files[].createdAt` | string (date-time) | no | | ## Example ```json { "id": "987e6543-e21a-11d4-a789-0242ac120002", "reference": "Order-JeanDupont-2024", "accountId": "123e4567-e89b-12d3-a456-426614174000", "status": "created", "customer": { "id": "123e4567-e89b-12d3-a456-426614174000", "email": "jean.dupont@example.fr", "firstname": "Jean", "lastname": "Dupont", "company": "Dupont Entreprises", "accountId": "c10e4fdf-a77d-457c-8fd6-2c0b29214800", "createdAt": "2024-07-01T09:26:55.737Z" }, "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" } }, "statusHistory": [ { "id": "987e6543-e21a-11d4-a789-0242ac120002", "status": "created", "createdAt": "2024-07-01T09:26:55.737Z" } ], "units": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "metadata": [], "files": [], "status": "created", "shipments": [], "createdAt": "2024-04-08T13:22:37.000Z" } ], "items": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "productId": "ntag424_pvccard_white", "name": "Jean Dupont", "quantity": 10 } ], "shipments": [ { "id": "123e4567-e89b-12d3-a456-426614174000", "trackerId": "1234567890", "trackingNumber": "1Z999AA10123456784", "unitsByProduct": { "ntag424_pvccard_white": 4 } } ], "total": 50.99, "files": [ { "id": "3f1c2b7a-5d4e-4f60-9a8b-1c2d3e4f5a6b", "mimeType": "application/pdf", "size": 48213, "filename": "letter.pdf", "createdAt": "2026-11-16T09:26:55.737Z" } ] } ``` --- # NFC The `NFC` object of the Printags API. | Field | Type | Required | Description | | --- | --- | --- | --- | | `type` | string: `empty`, `uri`, `text`, `dynamic` | no | | | `content` | string | no | | | `dynamic` | object | no | | | `dynamic.baseUrl` | string (uri) | yes | | | `dynamic.records` | object | yes | | | `dynamic.records.recordId` | integer | no | | | `dynamic.records.publicKey` | string | yes | | | `dynamic.records.privateKey` | string | yes | | | `options` | object | no | Encoding options applied during NFC encoding | | `options.lock` | boolean | no | If true, the NFC chip is permanently locked (read-only) after encoding. This is irreversible. | | `options.uid` | boolean | no | If true, the encoder reads and stores the chip UID without writing any payload. | ## Example ```json { "type": "empty", "content": "https://example.com", "dynamic": { "baseUrl": "https://example.com", "records": { "recordId": 1, "publicKey": "B5ADF942C642D16B2803CA672F47D11D", "privateKey": "82F87EB3F693B84BCC154A0373363A62" } }, "options": { "lock": true, "uid": false } } ``` --- # Job The processing of a firm order: queued by `createOrder`, made by the order worker five minutes later (at once for a test order), retried with a backoff of up to 30 minutes; above 100 cards it waits for the team's decision. | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string (uuid) | no | | | `type` | string | no | | | `status` | string: `pending`, `running`, `succeeded`, `failed` | no | | | `stage` | string: `queued`, `held_for_review`, `processing`, `manual_processing`, `done`, `failed` | no | Why the job has its status: `held_for_review` for an order above 100 cards waiting for the team, `manual_processing` when the team makes it by hand | | `orderId` | string (uuid) | no | | | `location` | string | no | Where to poll this job | | `retryAfter` | integer, nullable | no | Seconds before polling again; null once finished | | `createdAt` | string (date-time) | no | | | `updatedAt` | string (date-time) | no | | | `result` | object, nullable | no | Once `succeeded`: the order, to read with `getOrder` | | `result.orderId` | string (uuid) | no | | | `result.orderStatus` | string, nullable | no | | | `result.location` | string | no | | | `error` | object, nullable | no | Once `failed` | | `error.code` | string | no | | | `error.message` | string | no | | ## Example ```json { "id": "0b6f1c9e-3c1a-4e57-9f5e-6a2d8f1b7c40", "type": "order.treatment", "status": "pending", "stage": "queued", "orderId": "7b1e2a4c-0000-4000-8000-000000000000", "location": "/v2/accounts/@me/jobs/0b6f1c9e-3c1a-4e57-9f5e-6a2d8f1b7c40", "retryAfter": 300, "result": { "orderStatus": "validated", "location": "/v2/accounts/@me/orders/7b1e2a4c-0000-4000-8000-000000000000" }, "error": { "code": "ORDER_PROCESSING_FAILED" } } ``` --- # FileUpload Where and how to send the file: one `PUT` of its bytes to `uploadUrl`, with the same `Content-Type`, before `expiresAt`. The URL needs no Authorization header: give it to the browser that holds the file. | Field | Type | Required | Description | | --- | --- | --- | --- | | `uploadUrl` | string (uri) | no | `https://api.printags.com/v2/uploads/` (`https://sandbox-api.printags.com/...` when asked on the sandbox host). The token is signed, bound to the account and to the key's mode (test or live), valid 15 minutes and good for one file. Treat it as a secret until it is used. | | `method` | string: `PUT` | no | | | `contentType` | string: `image/png`, `image/jpeg`, `application/pdf` | no | | | `maxBytes` | integer | no | The largest file the URL takes (25 MB) | | `expiresAt` | string (date-time) | no | | ## Example ```json { "uploadUrl": "https://api.printags.com/v2/uploads/eyJhIjoiN2IxZTJhNGMifQ.c2lnbmF0dXJl", "method": "PUT", "contentType": "image/png", "maxBytes": 26214400, "expiresAt": "2026-11-10T13:15:00.000Z" } ``` --- # UploadedFile The stored file. Cite `fileId` in `printingVisuals` of `createOrder`, or in `shippingFiles` for a document shipped with the order, on the same account. | Field | Type | Required | Description | | --- | --- | --- | --- | | `fileId` | string (uuid) | no | | | `name` | string | no | | | `size` | integer | no | Bytes stored (a PDF is prepared for print, its size may change) | | `contentType` | string | no | | ## Example ```json { "fileId": "f0000000-0000-4000-8000-000000000009", "name": "recto.png", "size": 182044, "contentType": "image/png" } ``` --- # Quote What the order would debit as a firm order, computed as `createOrder` debits it: the account's plan, its volume tiers, the visual, the NFC encoding and the shipping. Euros excluding VAT, like the balance (VAT is added on the invoice). | Field | Type | Required | Description | | --- | --- | --- | --- | | `currency` | string: `eur` | no | | | `mode` | string: `test`, `production` | no | `test` with a test key: a test order debits nothing | | `totalExclVat` | number | no | The amount a firm order debits, shipping included | | `shippingExclVat` | number, nullable | no | | | `lines` | array of object | no | One per item, in the order of the request | | `lines[].modelId` | string | no | The item's catalogue product (its `productId`) | | `lines[].quantity` | integer | no | | | `lines[].unitPriceExclVat` | number | no | | | `lines[].lineTotalExclVat` | number | no | | | `lines[].unitCharges` | object | no | The unit price per charge: `model`, `printing`, `encoding`, `packaging` | | `balance` | number | no | The account's balance | | `enoughFunds` | boolean | no | Whether the balance covers `totalExclVat`; always true in test mode | ## Example ```json { "currency": "eur", "mode": "production", "totalExclVat": 42.5, "shippingExclVat": 2.5, "lines": [ { "modelId": "ntag213_pvccard_white", "quantity": 50, "unitPriceExclVat": 0.8, "lineTotalExclVat": 40, "unitCharges": { "model": 0.5, "printing": 0.3 } } ], "balance": 30, "enoughFunds": true } ``` --- # Webhook An endpoint the account's events are delivered to | Field | Type | Required | Description | | --- | --- | --- | --- | | `id` | string (uuid) | no | | | `endpoint` | string (uri) | no | | | `description` | string, nullable | no | | | `webhook_events` | array of object | no | The events it is subscribed to | | `webhook_events[].id` | string (uuid) | no | | | `webhook_events[].name` | string | no | | | `health` | object | no | Deliveries per state (in the list only) | | `health.total` | integer | no | | | `health.succeeded` | integer | no | | | `health.failed` | integer | no | | | `health.pending` | integer | no | | | `health.lastAt` | string (date-time), nullable | no | | | `createdAt` | string (date-time) | no | | | `updatedAt` | string (date-time) | no | | ## Example ```json { "id": "3c0e8f8a-0000-4000-8000-000000000001", "endpoint": "https://boutique.example/wp-json/printags/v1/webhook", "description": "WooCommerce", "webhook_events": [ { "name": "order.shipped" } ] } ```