---
title: "Printags API documentation"
description: "Reference of the Printags REST API: create orders of printed and NFC-encoded PVC cards, upload visuals, follow shipments. Generated from the OpenAPI document."
canonical: "https://docs.printags.com/"
last_updated: "2026-11-16"
---

# 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 <key>`. 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 <uploadUrl>` 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-<site>-<order id>`, 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=<epoch>,v1=<hex>`: compute the HMAC-SHA256 of `<t>.<raw body>` 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 <key>`. 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)
