Orders

Create an order

POST/v2/accounts/{accountId}/ordersTry it

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.

Request

Authorization

Bearer token

Send your API key in the Authorization header: Authorization: Bearer sk_test_…. A sk_test_ key creates and sees test orders only. Keys and test mode.

Path parameters
  • accountIdstringrequired
    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.
Headers
  • Idempotency-Keystring
    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.
  • Preferstring
    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.
Body application/json
  • isDraftboolean
    Indicates if the order is a draft
  • referencestring
    Reference for the order
  • carrierServiceIdstring
    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.
  • shipToAddressrequired
  • shippingFilesarray of string (uuid)
    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.
  • itemsarray of object
  • items[].quantityintegerrequired
    Quantity of the product
  • items[].productIdstring: pvccard_white, mifare1k_pvccard_white, ntag213_pvccard_white, ntag216_pvccard_white, ntag424_pvccard_white, ntag424_woodcardrequired
    Product ID of the product
  • items[].metadataobject
    Additional metadata for the product
  • items[].packagingIdstring
    ID of the packaging
  • items[].printingVisualsarray of string (uuid), nullable
    List of printing visuals for the product, obtained from the files API
  • items[].nfcNFC or array of NFC

Responses

200Order created successfully, or, for a replayed Idempotency-Key, the order already created (header Idempotent-Replayed true)
  • successboolean
  • orderIdstring
202With Prefer: respond-async, a firm order: created, debited and queued; its processing is the job to poll
  • successboolean
  • orderIdstring (uuid)
  • jobJob
400Bad 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).

Type: Error

401Unauthorized, authentication required, or an OAuth access token unknown, expired or revoked (INVALID_TOKEN)

Type: Error

402The account has no plan (SUBSCRIPTION_REQUIRED). Orders, test orders included, need an active plan or its free trial.

Type: Error

403The 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)

Type: Error

404Account 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).

Type: Error

429
500Internal server error

Type: Error

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