{"openapi":"3.0.0","info":{"title":"Printags - API Documentation, version 2","description":"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.\n\n## Versioning and deprecation\n\nThe 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.\n\n## Authentication with OAuth\n\nAn 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.\n\n## Test mode\n\nTest 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`).\n\n## Integrate a shop\n\nThe path of an e-commerce plugin (WooCommerce, Shopify...) whose customers upload their own visual:\n\n1. **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.\n2. **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).\n3. **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.\n4. **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.\n5. **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.\n6. **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`.","version":"2.0.0"},"servers":[{"url":"https://api.printags.com","description":"Main (production) server"},{"url":"https://sandbox-api.printags.com","description":"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."}],"tags":[{"name":"Accounts","description":"Endpoints related to account management"},{"name":"Orders","description":"Endpoints related to order management"},{"name":"Files","description":"Endpoints related to file management"},{"name":"Statuses","description":"Endpoints related to status management"},{"name":"Shipping","description":"Endpoints related to shipping rates and carrier availability"},{"name":"Products","description":"Endpoints related to the catalogue of products"},{"name":"Webhooks","description":"The account's event subscriptions"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"components":{"headers":{"Deprecation":{"description":"Present only on a deprecated version or operation (RFC 9745): the date its retirement was announced, as `@` followed by a Unix timestamp. Sent today by the routes of version 1 only.","schema":{"type":"string","example":"@1792886400"}},"Sunset":{"description":"Present only once a removal date is set (RFC 8594): the HTTP-date after which the version or operation stops answering. Version 1: Mon, 04 Jan 2027 00:00:00 GMT.","schema":{"type":"string","example":"Mon, 04 Jan 2027 00:00:00 GMT"}},"RateLimit-Limit":{"description":"Calls allowed in the 60-second window: 1200 per API key (per Bearer token), or 6000 per IP address for a call without a key (`listOrderStatuses`, `listShippingCarriers`, `calculateShippingRates`).","schema":{"type":"integer","example":1200}},"RateLimit-Remaining":{"description":"Calls left in the current window","schema":{"type":"integer","example":1199}},"RateLimit-Reset":{"description":"Seconds left before the window resets","schema":{"type":"integer","example":42}},"X-RateLimit-Limit":{"description":"Same value as `RateLimit-Limit`","schema":{"type":"integer","example":1200}},"X-RateLimit-Remaining":{"description":"Same value as `RateLimit-Remaining`","schema":{"type":"integer","example":1199}},"X-RateLimit-Reset":{"description":"Unix time, in seconds, at which the window resets (not a number of seconds left: use `RateLimit-Reset` for that)","schema":{"type":"integer","example":1793700000}},"Retry-After":{"description":"Seconds to wait before calling again","schema":{"type":"integer","example":12}}},"responses":{"TooManyRequests":{"description":"Rate limit exceeded (`code` `RATE_LIMITED`): wait for `Retry-After` seconds. Calls are limited to 1200 per minute per API key, and 6000 per minute per IP address for the calls without a key.","headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"},"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"success":false,"status":429,"code":"RATE_LIMITED","message":"Too many requests. Wait for the number of seconds in the Retry-After header before calling again."}}}}},"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key","description":"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."},"OAuth2":{"type":"oauth2","description":"An access token (`pta_...`) a person grants an application on ONE of the accounts they are a member of, in place of an API key: `Authorization: Bearer pta_...`. Authorization code flow (OAuth 2.1) for public clients: register the application once at `POST /oauth/register` (RFC 7591: `{ \"client_name\", \"redirect_uris\" }`, https URIs, or http on localhost; answers 201 with the `client_id`, no secret), send the person to `GET /oauth/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `state`, `scope=api`, `code_challenge` and `code_challenge_method=S256` (PKCE S256 is required: anything else comes back as `error=invalid_request`), let them pick the account on the consent screen, then exchange the `code` at `POST /oauth/token` (`grant_type=authorization_code`, `code`, `code_verifier`, `redirect_uri`, `client_id`). The answer: `access_token` (valid 1 hour), `refresh_token` (60 days, renewed on each use, not rotated), `token_type: Bearer`, `expires_in`, `scope: api`. Refresh with `grant_type=refresh_token`, `refresh_token`, `client_id`. `scope` takes exactly `api` or exactly `mcp` (the default when absent: the MCP server, not this API); a mix or another value comes back as `error=invalid_scope`. Discovery: `/.well-known/oauth-authorization-server`. Revoke with `POST /oauth/revoke` (`token`=the access or the refresh token, RFC 7009, always 200): the whole authorization ends, its tokens, and the webhook endpoints created with it; the person can also revoke it from the dashboard. Errors of these endpoints follow RFC 6749 (`error`, `error_description`: `invalid_grant`, `invalid_request`, `unsupported_grant_type`). On the API, a token acts exactly like the account's API key, on its own account only: the path's `accountId` must be that account or `@me`, otherwise 403 `ACCOUNT_ACCESS_DENIED`. Refusals: 401 `INVALID_TOKEN` (unknown, expired or revoked token, or the person's session is gone), 403 `INSUFFICIENT_SCOPE` (a token of scope `mcp`), 403 `ACCOUNT_ACCESS_DENIED` (another account in the path, or the person who connected the application is no longer a member of the account), 403 `SANDBOX_REQUIRES_TEST_KEY` (a real token on the sandbox host), 403 `UNAUTHORIZED_ROUTE` (a route that takes no API key). Test mode: an authorization started at `https://sandbox-api.printags.com/oauth/authorize` is a test one, for good (refresh included): its token acts like a `sk_test_` key on either host (test orders, neither debited nor manufactured); the consent and the code exchange may go through either host.","flows":{"authorizationCode":{"authorizationUrl":"https://api.printags.com/oauth/authorize","tokenUrl":"https://api.printags.com/oauth/token","refreshUrl":"https://api.printags.com/oauth/token","scopes":{"api":"The REST API on the one account the person picks at consent, as that account's API key would"}}}}},"schemas":{"Error":{"type":"object","description":"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.","properties":{"success":{"type":"boolean","example":false},"status":{"type":"integer","description":"HTTP status, repeated in the body","example":404},"code":{"type":"string","description":"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)","example":"ORDER_NOT_FOUND"},"message":{"type":"string","example":"Order 987e6543-e21a-11d4-a789-0242ac120002 not found"},"inputs":{"type":"object","description":"The values the error is about, when the endpoint gives them","additionalProperties":true},"error":{"type":"object","description":"Nested form of `code` and `message`, used by validation errors and unexpected errors","properties":{"code":{"type":"string","example":"VALIDATION_ERROR"},"message":{"type":"string"}}},"errors":{"type":"array","description":"Validation findings (request validator): one entry per invalid field, `path` naming it","items":{"type":"object","properties":{"path":{"type":"string","example":"/body/shipTo/address/city"},"message":{"type":"string"},"errorCode":{"type":"string"}}}}},"required":["success"]},"Account":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"displayname":{"type":"string","example":"John Doe"},"email":{"type":"string","format":"email","example":"johndoe@example.com"},"phone":{"type":"string","example":"+1234567890"},"balance":{"type":"number","format":"float","example":100.5},"minimal_balance":{"type":"number","example":0},"minimal_credit":{"type":"number","example":0},"fiscal_number":{"type":"string","example":"FR12345678901"},"subscription_plan":{"$ref":"#/components/schemas/SubscriptionPlan"},"options":{"type":"object","properties":{"lang":{"type":"string","example":"EN"},"payments":{"type":"object","properties":{"groupWithSubscription":{"type":"boolean","example":false}}}}},"createdAt":{"type":"string","format":"date-time","example":"2024-01-01T10:00:00.000Z"},"updatedAt":{"type":"string","format":"date-time","example":"2024-11-01T12:00:00.000Z"},"subscription_plan_source":{"type":"string","enum":["stripe","manual","shopify","woocommerce"],"readOnly":true,"description":"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":"stripe"}}},"Address":{"type":"object","description":"Address can be either a standard address or a service point (relay point). Use 'address' for home delivery or 'servicePoint' for relay point delivery.","properties":{"id":{"type":"string","nullable":true,"example":"123e4567-e89b-12d3-a456-426614174000"},"name":{"type":"string","example":"Jean Dupont","maxLength":38,"pattern":"^[a-zA-Z0-9à-öø-ÿÀ-ÖØ-ß-._ ']+$"},"phone":{"type":"string","example":"+33612345678"},"email":{"type":"string","format":"email","example":"jean.dupont@example.fr"},"address":{"type":"object","description":"Standard address for home delivery. Required if servicePoint is not provided.","properties":{"addressLine1":{"type":"string","example":"10 rue de la République","maxLength":38,"pattern":"^[a-zA-Z0-9à-öø-ÿÀ-ÖØ-ß-._ ',]+$"},"addressLine2":{"type":"string","nullable":true,"example":"Appartement 123","maxLength":38,"pattern":"^[a-zA-Z0-9à-öø-ÿÀ-ÖØ-ß-._ ',]+$"},"city":{"type":"string","example":"Paris","maxLength":35,"pattern":"^[a-zA-Z0-9à-öø-ÿÀ-ÖØ-ß-._ ']+$"},"postcode":{"type":"string","example":"75001"},"countryCode":{"type":"string","example":"FR","minLength":2,"maxLength":2}},"required":["addressLine1","city","postcode","countryCode"]},"servicePoint":{"type":"object","description":"Service point (relay point) for pickup delivery. Required if address is not provided. Use with a carrierServiceId that supports service points.","properties":{"id":{"type":"string","description":"The service point ID from the carrier (e.g., Sendcloud service point ID)","example":"12624766"},"country":{"type":"string","description":"ISO 2-letter country code of the service point","example":"LU","minLength":2,"maxLength":2}},"required":["id","country"]}},"required":["name","phone","email"]},"Customer":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"email":{"type":"string","format":"email","example":"jean.dupont@example.fr"},"firstname":{"type":"string","example":"Jean"},"lastname":{"type":"string","example":"Dupont"},"company":{"type":"string","example":"Dupont Entreprises"},"accountId":{"type":"string","example":"c10e4fdf-a77d-457c-8fd6-2c0b29214800","description":"The accountId of the owner of this customer"},"createdAt":{"type":"string","format":"date-time","example":"2024-07-01T09:26:55.737Z"}}},"Product":{"type":"object","properties":{"id":{"type":"string","description":"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.","example":"ntag424_pvccard_white"},"size":{"type":"object","properties":{"width":{"type":"number","example":0},"height":{"type":"number","example":0},"length":{"type":"number","example":0},"weight":{"type":"number","example":6}}},"prices":{"type":"array","description":"Pricing entries associated with the model.","items":{"type":"object"},"example":[]},"canBeEncoded":{"type":"boolean","example":true},"price":{"type":"object","nullable":true,"description":"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.","properties":{"currency":{"type":"string","example":"eur"},"quantity":{"type":"integer","example":1},"unitPriceExclVat":{"type":"number","example":2.1},"unitCharges":{"type":"object","properties":{"product":{"type":"number","example":1.7},"printing":{"type":"number","example":0.4}}}}}}},"Unit":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"product":{"$ref":"#/components/schemas/Product"},"metadata":{"type":"array","description":"Always empty, kept for compatibility (the card metadata stopped in June 2024)","items":{"type":"object"},"example":[]},"files":{"type":"array","description":"The files of the card's order item, its front and back visuals","items":{"type":"object"},"example":[]},"status":{"type":"string","description":"Current status of the product","example":"created"},"shipments":{"type":"array","description":"Shipping information associated with the product","items":{"type":"object"},"example":[]},"createdAt":{"type":"string","format":"date-time","example":"2024-04-08T13:22:37.000Z"}}},"Item":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"productId":{"type":"string","example":"ntag424_pvccard_white"},"name":{"type":"string","example":"Jean Dupont"},"quantity":{"type":"integer","example":10},"nfc":{"$ref":"#/components/schemas/NFC"},"product":{"$ref":"#/components/schemas/Product"}}},"SubscriptionPlan":{"type":"object","properties":{"id":{"type":"string","example":"987e6543-e21a-11d4-a789-0242ac120002"},"displayname":{"type":"string","example":"Basic Plan"},"price":{"type":"number","example":49.99},"shippingLetter":{"type":"boolean","example":true},"whiteLabel":{"type":"boolean","example":false}}},"Shipment":{"type":"object","properties":{"id":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"trackerId":{"type":"string","example":"1234567890"},"trackingNumber":{"type":"string","example":"1Z999AA10123456784"},"unitsByProduct":{"type":"object","description":"The shipment's units counted per catalogue product, keyed by the product's id","additionalProperties":{"type":"integer"},"example":{"ntag424_pvccard_white":4}}}},"ShippingCarrier":{"type":"object","description":"A carrier service available for a destination, with its computed price.","properties":{"id":{"type":"string","description":"Carrier service identifier to pass as carrierServiceId when creating an order.","example":"lpf_standard"},"name":{"type":"string","description":"Human-readable carrier service name.","example":"La Poste - Lettre Suivie"},"code":{"type":"string","description":"Internal carrier code.","example":"laposte"},"hasServicePoints":{"type":"boolean","description":"Whether this service delivers to service points (relay points / lockers).","example":false},"apiProvider":{"type":"string","description":"Backend provider handling this carrier.","example":"laposte"},"countries":{"type":"array","items":{"type":"string"},"example":["FR","BE"]},"enabledCountries":{"type":"array","description":"Destination countries this service is enabled for ('*' means all).","items":{"type":"string"},"example":["FR","BE","LU"]},"price":{"type":"number","format":"float","description":"Price for the requested destination and weight, in EUR. Only services with a price greater than 0 are returned.","example":2.3},"weightTier":{"type":"integer","nullable":true,"description":"Weight threshold (in grams) of the matched price tier.","example":0},"priceTiers":{"type":"object","description":"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.","example":{"0":2.3,"250":3}},"minWeight":{"type":"integer","description":"Minimum supported weight in grams.","example":0},"maxWeight":{"type":"integer","description":"Maximum supported weight in grams.","example":3000}}},"ShippingRate":{"type":"object","description":"A carrier service available for a set of items, with its computed price.","properties":{"id":{"type":"string","description":"Carrier service identifier to pass as carrierServiceId when creating an order.","example":"lpf_standard"},"name":{"type":"string","example":"La Poste - Lettre Suivie"},"code":{"type":"string","example":"laposte"},"serviceCode":{"type":"string","nullable":true,"description":"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.","example":"chrono_18"},"hasServicePoints":{"type":"boolean","example":false},"price":{"type":"number","format":"float","description":"Price for the computed weight and destination, in EUR.","example":3},"weightTier":{"type":"integer","nullable":true,"description":"Weight threshold (in grams) of the matched price tier.","example":250}}},"ShippingEnvelope":{"type":"object","description":"The packaging envelope selected for the items, based on total volume.","properties":{"id":{"type":"string","description":"Envelope identifier, or 'custom' when no standard envelope matches the volume.","example":"custom"},"name":{"type":"string","example":"Emballage spécial"},"weight":{"type":"number","description":"Envelope weight in grams, included in the total shipping weight.","example":50}}},"Order":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"987e6543-e21a-11d4-a789-0242ac120002"},"reference":{"type":"string","example":"Order-JeanDupont-2024"},"accountId":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"status":{"type":"string","example":"created"},"customer":{"$ref":"#/components/schemas/Customer"},"shipTo":{"$ref":"#/components/schemas/Address"},"statusHistory":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"987e6543-e21a-11d4-a789-0242ac120002"},"status":{"type":"string","example":"created"},"createdAt":{"type":"string","format":"date-time","example":"2024-07-01T09:26:55.737Z"}}}},"units":{"type":"array","items":{"$ref":"#/components/schemas/Unit"}},"items":{"type":"array","items":{"$ref":"#/components/schemas/Item"}},"metadata":{"type":"object","nullable":true,"description":"Additional metadata for the order","example":{}},"shipments":{"description":"Shipping information associated with the order","type":"array","items":{"$ref":"#/components/schemas/Shipment"}},"total":{"type":"number","example":50.99},"files":{"description":"The documents shipped with the order (`shippingFiles` of `createOrder`). Returned by `getOrder` only.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","example":"3f1c2b7a-5d4e-4f60-9a8b-1c2d3e4f5a6b"},"mimeType":{"type":"string","example":"application/pdf"},"size":{"type":"integer","description":"Size in bytes","example":48213},"filename":{"type":"string","example":"letter.pdf"},"createdAt":{"type":"string","format":"date-time","example":"2026-11-16T09:26:55.737Z"}}}}}},"NFC":{"type":"object","properties":{"type":{"type":"string","enum":["empty","uri","text","dynamic"],"example":"empty"},"content":{"type":"string","example":"https://example.com"},"dynamic":{"type":"object","required":["baseUrl","records"],"properties":{"baseUrl":{"type":"string","format":"uri","example":"https://example.com"},"records":{"type":"object","required":["publicKey","privateKey"],"properties":{"recordId":{"type":"integer","example":1},"publicKey":{"type":"string","example":"B5ADF942C642D16B2803CA672F47D11D","minLength":32,"maxLength":32},"privateKey":{"type":"string","example":"82F87EB3F693B84BCC154A0373363A62","minLength":32,"maxLength":32}}}}},"options":{"type":"object","description":"Encoding options applied during NFC encoding","properties":{"lock":{"type":"boolean","description":"If true, the NFC chip is permanently locked (read-only) after encoding. This is irreversible.","default":false,"example":true},"uid":{"type":"boolean","description":"If true, the encoder reads and stores the chip UID without writing any payload.","example":false}}}}},"Job":{"type":"object","description":"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.","properties":{"id":{"type":"string","format":"uuid","example":"0b6f1c9e-3c1a-4e57-9f5e-6a2d8f1b7c40"},"type":{"type":"string","example":"order.treatment"},"status":{"type":"string","enum":["pending","running","succeeded","failed"],"example":"pending"},"stage":{"type":"string","enum":["queued","held_for_review","processing","manual_processing","done","failed"],"description":"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","example":"queued"},"orderId":{"type":"string","format":"uuid","example":"7b1e2a4c-0000-4000-8000-000000000000"},"location":{"type":"string","description":"Where to poll this job","example":"/v2/accounts/@me/jobs/0b6f1c9e-3c1a-4e57-9f5e-6a2d8f1b7c40"},"retryAfter":{"type":"integer","nullable":true,"description":"Seconds before polling again; null once finished","example":300},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"result":{"type":"object","nullable":true,"description":"Once `succeeded`: the order, to read with `getOrder`","properties":{"orderId":{"type":"string","format":"uuid"},"orderStatus":{"type":"string","nullable":true,"example":"validated"},"location":{"type":"string","example":"/v2/accounts/@me/orders/7b1e2a4c-0000-4000-8000-000000000000"}}},"error":{"type":"object","nullable":true,"description":"Once `failed`","properties":{"code":{"type":"string","example":"ORDER_PROCESSING_FAILED"},"message":{"type":"string"}}}}},"FileUpload":{"type":"object","description":"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.","properties":{"uploadUrl":{"type":"string","format":"uri","description":"`https://api.printags.com/v2/uploads/<token>` (`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.","example":"https://api.printags.com/v2/uploads/eyJhIjoiN2IxZTJhNGMifQ.c2lnbmF0dXJl"},"method":{"type":"string","enum":["PUT"],"example":"PUT"},"contentType":{"type":"string","enum":["image/png","image/jpeg","application/pdf"],"example":"image/png"},"maxBytes":{"type":"integer","description":"The largest file the URL takes (25 MB)","example":26214400},"expiresAt":{"type":"string","format":"date-time","example":"2026-11-10T13:15:00.000Z"}}},"UploadedFile":{"type":"object","description":"The stored file. Cite `fileId` in `printingVisuals` of `createOrder`, or in `shippingFiles` for a document shipped with the order, on the same account.","properties":{"fileId":{"type":"string","format":"uuid","example":"f0000000-0000-4000-8000-000000000009"},"name":{"type":"string","example":"recto.png"},"size":{"type":"integer","description":"Bytes stored (a PDF is prepared for print, its size may change)","example":182044},"contentType":{"type":"string","example":"image/png"}}},"Quote":{"type":"object","description":"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).","properties":{"currency":{"type":"string","enum":["eur"],"example":"eur"},"mode":{"type":"string","enum":["test","production"],"description":"`test` with a test key: a test order debits nothing","example":"production"},"totalExclVat":{"type":"number","description":"The amount a firm order debits, shipping included","example":42.5},"shippingExclVat":{"type":"number","nullable":true,"example":2.5},"lines":{"type":"array","description":"One per item, in the order of the request","items":{"type":"object","properties":{"modelId":{"type":"string","description":"The item's catalogue product (its `productId`)","example":"ntag213_pvccard_white"},"quantity":{"type":"integer","example":50},"unitPriceExclVat":{"type":"number","example":0.8},"lineTotalExclVat":{"type":"number","example":40},"unitCharges":{"type":"object","description":"The unit price per charge: `model`, `printing`, `encoding`, `packaging`","additionalProperties":{"type":"number"},"example":{"model":0.5,"printing":0.3}}}}},"balance":{"type":"number","description":"The account's balance","example":30},"enoughFunds":{"type":"boolean","description":"Whether the balance covers `totalExclVat`; always true in test mode","example":true}}},"Webhook":{"type":"object","description":"An endpoint the account's events are delivered to","properties":{"id":{"type":"string","format":"uuid","example":"3c0e8f8a-0000-4000-8000-000000000001"},"endpoint":{"type":"string","format":"uri","example":"https://boutique.example/wp-json/printags/v1/webhook"},"description":{"type":"string","nullable":true,"example":"WooCommerce"},"webhook_events":{"type":"array","description":"The events it is subscribed to","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"order.shipped"}}}},"health":{"type":"object","description":"Deliveries per state (in the list only)","properties":{"total":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"},"pending":{"type":"integer"},"lastAt":{"type":"string","format":"date-time","nullable":true}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}},"paths":{"/v2/accounts/@me":{"get":{"operationId":"getCurrentAccount","summary":"Get the authenticated account","description":"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).","tags":["Accounts"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"responses":{"200":{"description":"Successfully retrieved account details","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"account":{"$ref":"#/components/schemas/Account"}}}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}":{"get":{"operationId":"getAccount","summary":"Get an account by ID","description":"Returns an account's details. An API key only reads the account that holds it (use `@me` or its own id).","tags":["Accounts"],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique identifier of the account"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"responses":{"200":{"description":"Successfully retrieved account details","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"account":{"$ref":"#/components/schemas/Account"}}}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/orders/find":{"get":{"operationId":"findOrders","summary":"Find orders by reference or metadata","description":"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.","tags":["Orders"],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique identifier of the account"},{"in":"query","name":"metadata","schema":{"type":"string","example":"internalOrderId:987e6543-e21a-11d4-a789-0242ac120002"},"description":"Filter orders based on metadata"},{"in":"query","name":"reference","schema":{"type":"string","example":"reference:987e6543-e21a-11d4-a789-0242ac120002"},"description":"Filter orders based on reference"},{"in":"query","name":"fields","schema":{"type":"string","example":"fields:id,reference"},"description":"Get only wanted fields"}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"responses":{"200":{"description":"Successfully retrieved orders","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/orders/{orderId}":{"get":{"operationId":"getOrder","summary":"Get an order by ID","description":"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.","tags":["Orders"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique identifier of the account"},{"in":"path","name":"orderId","required":true,"schema":{"type":"string","example":"987e6543-e21a-11d4-a789-0242ac120002"},"description":"Unique identifier of the order"}],"responses":{"200":{"description":"Successfully retrieved order details","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"order":{"$ref":"#/components/schemas/Order"}}}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/orders":{"get":{"operationId":"listOrders","x-eov-allow-unknown-query-parameters":true,"summary":"List the orders of an account","description":"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`.","tags":["Orders"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"Unique identifier of the account, or the alias `@me` for the account authenticated by the token."},{"in":"query","name":"page","required":false,"schema":{"type":"string","example":"1"},"description":"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."},{"in":"query","name":"per_page","required":false,"schema":{"type":"string","example":"20"},"description":"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."},{"in":"query","name":"status","required":false,"allowReserved":true,"schema":{"type":"string","example":"draft,in_queue"},"description":"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."},{"in":"query","name":"search","required":false,"allowReserved":true,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"example":"Dupont"},"description":"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."},{"in":"query","name":"cursor","required":false,"schema":{"type":"string","example":"WyIyMDI2LTExLTA5VDEwOjAwOjAwLjAwMFoiLCI3YjFlMmE0Yy0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAiXQ"},"description":"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`."},{"in":"query","name":"limit","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"example":20},"description":"Page size, 1 to 100 (default: `per_page`, else 20). Any other value is refused with 400 `INVALID_LIMIT`."}],"responses":{"200":{"description":"A page of orders","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"orders":{"type":"array","description":"The orders of the page, most recent first. Empty when the page is past the last one.","items":{"allOf":[{"$ref":"#/components/schemas/Order"},{"type":"object","properties":{"recipient":{"type":"object","description":"The delivery address's name and email, present when the order has a delivery address. It replaces `shipTo` in this list.","properties":{"name":{"type":"string","example":"Jean Dupont"},"email":{"type":"string","example":"jean@example.com"}}}}}]}},"pagination":{"type":"object","properties":{"total":{"type":"integer","description":"Number of orders matching the filters, all pages together","example":134},"page":{"type":"integer","description":"The page returned","example":1},"per_page":{"type":"integer","description":"The page size used","example":20},"limit":{"type":"integer","description":"The page size used","example":20},"next_cursor":{"type":"string","nullable":true,"description":"Pass it as `cursor` to get the next page; null on the last page","example":"WyIyMDI2LTExLTA5VDEwOjAwOjAwLjAwMFoiLCI3YjFlMmE0Yy0wMDAwLTQwMDAtODAwMC0wMDAwMDAwMDAwMDAiXQ"},"has_more":{"type":"boolean","description":"Whether orders follow this page","example":true}},"description":"Without `cursor`: `total`, `page`, `per_page`, `limit`, `next_cursor` and `has_more`. With `cursor`: `limit`, `next_cursor` and `has_more`.","required":["next_cursor","has_more"]}}}}}},"400":{"description":"`cursor` is not a `next_cursor` of this API (`INVALID_CURSOR`), or `limit` is not 1 to 100 (`INVALID_LIMIT`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createOrder","summary":"Create an order","description":"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.","tags":["Orders"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"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."},{"in":"header","name":"Idempotency-Key","required":false,"schema":{"type":"string","minLength":8,"maxLength":100,"example":"5f0c3b1e-8f4a-4b0e-9a57-2d1c6b7e9a10"},"description":"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."},{"in":"header","name":"Prefer","required":false,"schema":{"type":"string","example":"respond-async"},"description":"`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."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"isDraft":{"type":"boolean","description":"Indicates if the order is a draft","example":false},"reference":{"type":"string","description":"Reference for the order","example":"Order-JeanDupont-2024"},"carrierServiceId":{"type":"string","description":"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.","example":"lpf_standard"},"shipTo":{"$ref":"#/components/schemas/Address"},"shippingFiles":{"type":"array","description":"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":{"type":"string","format":"uuid"},"example":["3f1c2b7a-5d4e-4f60-9a8b-1c2d3e4f5a6b"]},"items":{"type":"array","items":{"type":"object","properties":{"quantity":{"type":"integer","description":"Quantity of the product","example":10,"default":1},"productId":{"type":"string","enum":["pvccard_white","mifare1k_pvccard_white","ntag213_pvccard_white","ntag216_pvccard_white","ntag424_pvccard_white","ntag424_woodcard"],"description":"Product ID of the product","example":"ntag424_pvccard_white"},"metadata":{"type":"object","description":"Additional metadata for the product","example":{"internalId":"a3d3842e-89c0-41d2-9384-2e89c021d2bc"}},"packagingId":{"type":"string","description":"ID of the packaging","example":"aluminum_protection"},"printingVisuals":{"type":"array","description":"List of printing visuals for the product, obtained from the files API","items":{"type":"string","format":"uuid","nullable":true},"example":["0806a77d-8007-4cfc-86a7-7d80079cfc8f","a77d8007-007c-fc86-7a7d-80079cfc8f0"]},"nfc":{"oneOf":[{"$ref":"#/components/schemas/NFC"},{"type":"array","items":{"$ref":"#/components/schemas/NFC"}}]}},"required":["quantity","productId"]}}},"required":["shipTo"]}}}},"responses":{"200":{"description":"Order created successfully, or, for a replayed `Idempotency-Key`, the order already created (header `Idempotent-Replayed true`)","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Idempotent-Replayed":{"description":"`true` when the response replays the order a previous call created with the same `Idempotency-Key`; absent otherwise","schema":{"type":"string","example":"true"}},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"orderId":{"type":"string","example":"987e6543-e21a-11d4-a789-0242ac120002"}}}}}},"202":{"description":"With `Prefer: respond-async`, a firm order: created, debited and queued; its processing is the job to poll","headers":{"Location":{"description":"The job to poll (`getJob`)","schema":{"type":"string","example":"/v2/accounts/7b1e2a4c-0000-4000-8000-000000000001/jobs/0b6f1c9e-3c1a-4e57-9f5e-6a2d8f1b7c40"}},"Retry-After":{"description":"Seconds before the first poll is worth it","schema":{"type":"integer","example":300}},"Preference-Applied":{"description":"`respond-async`","schema":{"type":"string","example":"respond-async"}},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"orderId":{"type":"string","format":"uuid"},"job":{"$ref":"#/components/schemas/Job"}}}}}},"400":{"description":"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).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no plan (`SUBSCRIPTION_REQUIRED`). Orders, test orders included, need an active plan or its free trial.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"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`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/files":{"post":{"operationId":"uploadFile","summary":"Upload a visual file","description":"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).","tags":["Files"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique identifier of the account"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload"}}}}}},"responses":{"201":{"description":"File uploaded successfully","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"image/*":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Bad request, invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Account not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/files/{fileId}":{"get":{"operationId":"getFile","summary":"Get a file by ID","description":"Returns a stored file. This route does not check the API key.","tags":["Files"],"security":[],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique identifier of the account"},{"in":"path","name":"fileId","required":true,"schema":{"type":"string","example":"987e6543-e21a-11d4-a789-0242ac120002"},"description":"Unique identifier of the file"}],"responses":{"200":{"description":"Successfully retrieved file details","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"file":{"type":"object","properties":{"id":{"type":"string","example":"987e6543-e21a-11d4-a789-0242ac120002"},"name":{"type":"string","example":"example.pdf"},"size":{"type":"number","example":1024},"createdAt":{"type":"string","format":"date-time","example":"2024-07-01T09:26:55.737Z"}}}}}}},"headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}}},"404":{"description":"File not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/orders/{orderId}/validate":{"post":{"operationId":"validateOrder","summary":"Validate a draft order","description":"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.","tags":["Orders"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"123e4567-e89b-12d3-a456-426614174000"},"description":"Unique identifier of the account"},{"in":"path","name":"orderId","required":true,"schema":{"type":"string","example":"987e6543-e21a-11d4-a789-0242ac120002"},"description":"Unique identifier of the order"}],"responses":{"200":{"description":"Order validated successfully","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"prices":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer","example":0},"quantity":{"type":"integer","example":10},"productId":{"type":"string","example":"ntag424_pvccard_white"},"unit_charges":{"type":"object","properties":{"encoding":{"type":"number","example":0.5,"nullable":true},"product":{"type":"number","example":0.5,"nullable":true},"printing":{"type":"number","example":0.1,"nullable":true},"packaging":{"type":"number","example":0.2,"nullable":true},"recordOptions":{"type":"number","example":0.3,"nullable":true}}},"charges":{"type":"object","properties":{"encoding":{"type":"number","example":5,"nullable":true},"product":{"type":"number","example":5,"nullable":true},"printing":{"type":"number","example":1,"nullable":true},"packaging":{"type":"number","example":2,"nullable":true},"recordOptions":{"type":"number","example":3,"nullable":true}}},"price":{"type":"number","example":4.49},"unit_price":{"type":"number","example":4.49}}}},"shipping":{"type":"object","properties":{"transporter":{"type":"string","example":"default"},"price":{"type":"number","example":5.99}}},"total":{"type":"number","example":50.99}}}}}}}},"400":{"description":"Bad request, invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Order not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/orders/{orderId}/simulate":{"post":{"operationId":"simulateOrderStatus","summary":"Simulate a status change on a test order","description":"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.","tags":["Orders"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"Unique identifier of the account. You can also use the alias `@me`."},{"in":"path","name":"orderId","required":true,"schema":{"type":"string","example":"987e6543-e21a-11d4-a789-0242ac120002"},"description":"Unique identifier of the test order"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Any status of the order life cycle, see `GET /orders/statuses`.","example":"shipped"}},"required":["status"]}}}},"responses":{"200":{"description":"Status changed, webhooks sent","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"order":{"type":"object","description":"The order in its new status"}}}}}},"400":{"description":"Missing or unknown status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Test order not found. Only orders created with a `sk_test_` key can be simulated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The test order is still being processed (`TEST_ORDER_NOT_READY`), retry in a few seconds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/statuses":{"get":{"operationId":"listOrderStatuses","summary":"List order statuses","description":"Returns every status of the order life cycle (`id` and `name`). This route does not need authentication.","tags":["Statuses"],"security":[],"responses":{"200":{"description":"Successfully retrieved all statuses","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","example":0},"name":{"type":"string","example":"created"}}}}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/shipping/carriers":{"get":{"operationId":"listShippingCarriers","summary":"List carriers for a destination","description":"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.","tags":["Shipping"],"security":[],"parameters":[{"in":"query","name":"to_country","required":true,"schema":{"type":"string","minLength":2,"maxLength":2,"example":"FR"},"description":"ISO 2-letter destination country code."},{"in":"query","name":"to_postal_code","required":false,"schema":{"type":"string","example":"75001"},"description":"Destination postal code (reserved for postal-code-aware pricing)."},{"in":"query","name":"weight","required":false,"schema":{"type":"integer","example":30},"description":"Total weight in grams. When provided, only services whose weight range covers it are returned."}],"responses":{"200":{"description":"Successfully retrieved available carriers","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"count":{"type":"integer","example":2},"carriers":{"type":"array","items":{"$ref":"#/components/schemas/ShippingCarrier"}}}}}}},"400":{"description":"Bad request, missing required parameter (e.g. to_country)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/shipping/rates":{"post":{"operationId":"calculateShippingRates","summary":"Calculate shipping rates","description":"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.","tags":["Shipping"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"to_country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 2-letter destination country code.","example":"FR"},"to_postal_code":{"type":"string","description":"Destination postal code (reserved for postal-code-aware pricing).","example":"75001"},"items":{"type":"array","minItems":1,"description":"Items to ship. Weight and volume are derived from each model (and optional packaging).","items":{"type":"object","properties":{"productId":{"type":"string","enum":["pvccard_white","mifare1k_pvccard_white","ntag213_pvccard_white","ntag216_pvccard_white","ntag424_pvccard_white","ntag424_woodcard"],"description":"Product ID of the item.","example":"ntag424_pvccard_white"},"packagingId":{"type":"string","nullable":true,"description":"Optional packaging ID, added to the item weight and volume.","example":"aluminum_protection"},"quantity":{"type":"integer","default":1,"description":"Number of units for this item.","example":10}},"required":["productId"]}}},"required":["to_country","items"]}}}},"responses":{"200":{"description":"Successfully calculated shipping rates","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"weight":{"type":"integer","description":"Total shipping weight in grams (items + envelope).","example":110},"volume":{"type":"number","description":"Total items volume in cm³.","example":42.5},"envelope":{"$ref":"#/components/schemas/ShippingEnvelope"},"count":{"type":"integer","example":2},"carriers":{"type":"array","items":{"$ref":"#/components/schemas/ShippingRate"}}}}}}},"400":{"description":"Bad request, missing to_country or items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No matching models found for the provided items","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/products":{"get":{"operationId":"listProducts","summary":"List available products","description":"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.","tags":["Products"],"parameters":[{"name":"include","in":"query","required":false,"description":"`prices` adds the account's price of one printed card to each model.","schema":{"type":"string","enum":["prices"]}}],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"responses":{"200":{"description":"Successfully retrieved available models","headers":{"RateLimit-Limit":{"$ref":"#/components/headers/RateLimit-Limit"},"RateLimit-Remaining":{"$ref":"#/components/headers/RateLimit-Remaining"},"RateLimit-Reset":{"$ref":"#/components/headers/RateLimit-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/X-RateLimit-Reset"},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"models":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/jobs/{jobId}":{"get":{"operationId":"getJob","summary":"Get the job of a firm order","description":"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).","tags":["Orders"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"Unique identifier of the account, or the alias `@me` for the account authenticated by the token."},{"in":"path","name":"jobId","required":true,"schema":{"type":"string","format":"uuid"},"description":"The `job.id` of the 202 answer"}],"responses":{"200":{"description":"The job","headers":{"Retry-After":{"description":"While pending or running: seconds before polling again","schema":{"type":"integer","example":300}},"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}},"content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"job":{"$ref":"#/components/schemas/Job"}}}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No job of this id for the authenticated account and mode (`JOB_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/files/uploads":{"post":{"operationId":"createFileUpload","summary":"Get a signed URL to upload a visual","description":"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.","tags":["Files"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"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`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fileName","contentType"],"properties":{"fileName":{"type":"string","minLength":1,"maxLength":200,"description":"Kept as the file's name (path parts removed)","example":"recto.png"},"contentType":{"type":"string","enum":["image/png","image/jpeg","application/pdf"],"example":"image/png"}}}}}},"responses":{"201":{"description":"The upload URL","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"upload":{"$ref":"#/components/schemas/FileUpload"}}}}},"headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}}},"400":{"description":"`fileName` or `contentType` missing (`MISSING_PARAMETERS`), or a type other than PNG, JPEG or PDF (`UNSUPPORTED_FILE_TYPE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/uploads/{token}":{"put":{"operationId":"uploadFileToSignedUrl","summary":"Upload a visual to a signed URL","description":"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`).","tags":["Files"],"security":[],"parameters":[{"in":"path","name":"token","required":true,"schema":{"type":"string"},"description":"The signed token, as `uploadUrl` holds it"}],"requestBody":{"required":true,"content":{"image/png":{"schema":{"type":"string","format":"binary"}},"image/jpeg":{"schema":{"type":"string","format":"binary"}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"The file is stored","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"file":{"$ref":"#/components/schemas/UploadedFile"}}}}},"headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}}},"400":{"description":"Empty body (`EMPTY_BODY`), or content that is not the announced type (`CONTENT_TYPE_MISMATCH`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Forged or expired token, or one made for another use (`INVALID_UPLOAD_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A live URL used on the sandbox host (`SANDBOX_REQUIRES_TEST_KEY`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The URL already stored its file (`UPLOAD_LINK_USED`): ask for a new one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Over 25 MB (`FILE_TOO_LARGE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"A PDF that cannot be prepared for print (`INVALID_FILE`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many uploads from this address (`RATE_LIMITED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error (`UPLOAD_FAILED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/orders/quote":{"post":{"operationId":"quoteOrder","summary":"Quote an order","description":"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.","tags":["Orders"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"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`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"Delivery country (ISO 3166-1 alpha-2), instead of `shipTo`","example":"FR"},"shipTo":{"type":"object","description":"As in `createOrder`: only its country is read"},"carrierServiceId":{"type":"string","description":"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.","example":"lpf_standard"},"items":{"type":"array","items":{"type":"object","properties":{"quantity":{"type":"integer","description":"Quantity of the product","example":10,"default":1},"productId":{"type":"string","enum":["pvccard_white","mifare1k_pvccard_white","ntag213_pvccard_white","ntag216_pvccard_white","ntag424_pvccard_white","ntag424_woodcard"],"description":"Product ID of the product","example":"ntag424_pvccard_white"},"metadata":{"type":"object","description":"Additional metadata for the product","example":{"internalId":"a3d3842e-89c0-41d2-9384-2e89c021d2bc"}},"packagingId":{"type":"string","description":"ID of the packaging","example":"aluminum_protection"},"printingVisuals":{"type":"array","description":"List of printing visuals for the product, obtained from the files API","items":{"type":"string","format":"uuid","nullable":true},"example":["0806a77d-8007-4cfc-86a7-7d80079cfc8f","a77d8007-007c-fc86-7a7d-80079cfc8f0"]},"nfc":{"oneOf":[{"$ref":"#/components/schemas/NFC"},{"type":"array","items":{"$ref":"#/components/schemas/NFC"}}]}},"required":["quantity","productId"]}}}}}}},"responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"quote":{"$ref":"#/components/schemas/Quote"}}}}},"headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}}},"400":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The account has no plan, so no price (`SUBSCRIPTION_REQUIRED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhook endpoints","description":"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=<epoch seconds>,v1=<hex>`, where `v1` is the HMAC-SHA256, keyed by the endpoint's `secret` (`whsec_...`), of `<t>.<raw body>`: 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`.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"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":{"200":{"description":"The endpoints","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}},"headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhook","summary":"Create a webhook endpoint","description":"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=<epoch seconds>,v1=<hex>`, where `v1` is the HMAC-SHA256, keyed by the endpoint's `secret` (`whsec_...`), of `<t>.<raw body>`: 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`.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"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`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","maxLength":255,"example":"https://boutique.example/wp-json/printags/v1/webhook"},"events":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","example":"order.updated"},"example":["order.updated","order.shipped"]},"description":{"type":"string","nullable":true,"example":"WooCommerce"}}}}}},"responses":{"200":{"description":"The endpoint, and its signing secret","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"secret":{"type":"string","description":"The HMAC key of `X-Printags-Signature`, given only here","example":"whsec_0f3c..."},"webhook":{"$ref":"#/components/schemas/Webhook"}}}}},"headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}}},"400":{"description":"`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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The account already holds 25 endpoints (`WEBHOOK_LIMIT_REACHED`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v2/accounts/{accountId}/webhooks/{webhookId}":{"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook endpoint","description":"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.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["api"]}],"parameters":[{"in":"path","name":"accountId","required":true,"schema":{"type":"string","example":"@me"},"description":"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`."},{"in":"path","name":"webhookId","required":true,"schema":{"type":"string","format":"uuid"},"description":"The endpoint's `id`"}],"responses":{"200":{"description":"The deleted endpoint","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"webhook":{"$ref":"#/components/schemas/Webhook"}}}}},"headers":{"Deprecation":{"$ref":"#/components/headers/Deprecation"},"Sunset":{"$ref":"#/components/headers/Sunset"}}},"401":{"description":"Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (`INVALID_TOKEN`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"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`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No endpoint of this id for the account and mode (`WEBHOOK_NOT_FOUND`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}