Orders
Create an order
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
accountIdstringrequiredUnique identifier of the account. You can also use the alias@meto target the account authenticated by the token, without having to fetch its id first.
Headers
Idempotency-KeystringOptional. 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 anIdempotent-Replayed: trueheader, 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'smetadata(mcp_idempotency_key), shared with the MCPidempotencyKey. Without the header, nothing changes. A key shorter than 8 or longer than 100 characters is refused with 400.Preferstringrespond-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
isDraftbooleanIndicates if the order is a draftreferencestringReference for the ordercarrierServiceIdstringID 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.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 withuploadFile, on the same account. An unknown id or a file of another account is refused with 404FILE_NOT_FOUND, on a draft as on a firm order, which is then neither created nor debited.getOrderreturns them infiles.itemsarray of objectitems[].quantityintegerrequiredQuantity of the productitems[].productIdstring:pvccard_white,mifare1k_pvccard_white,ntag213_pvccard_white,ntag216_pvccard_white,ntag424_pvccard_white,ntag424_woodcardrequiredProduct ID of the productitems[].metadataobjectAdditional metadata for the productitems[].packagingIdstringID of the packagingitems[].printingVisualsarray of string (uuid), nullableList of printing visuals for the product, obtained from the files API
Responses
200Order created successfully, or, for a replayed Idempotency-Key, the order already created (header Idempotent-Replayed true)
successbooleanorderIdstring
202With Prefer: respond-async, a firm order: created, debited and queued; its processing is the job to poll
successbooleanorderIdstring (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