Orders

An order asks for cards to be produced for one or more card holders. Each person on an order becomes an order item. The name, ID and photo are snapshotted onto the item when the order is created, so a later reprint reproduces the original card.

Order status

draft ► submitted ► in_production ► printed ► shipped ► completed

An order can be cancelled from draft, submitted or in_production. The API can move an order only to submitted or cancelled; production statuses are set by whoever is printing.

List orders

GET/ordersscope: orders:read

Query: page, pageSize, and status. Newest first.

Each order includes id, orderNumber (for example ACME-2027-0412), status, priority, notes, dueDate, currency, subtotal, taxAmount, totalAmount, submittedAt, completedAt, createdAt and updatedAt. Monetary amounts are decimal strings in the order’s currency.

Create an order

POST/ordersscope: orders:write

Field	Type	Notes
cardHolderIds	array of uuid, required	1 to 5000 holders
templateVersionId	uuid	Card design to use for every line. Alias: templateId. If omitted, each person gets the design for their holder type, or the organisation default
priority	enum, default standard	standard, rush, emergency
notes	string, max 2000
dueDate	YYYY-MM-DD
idempotencyKey	string, 8 to 128 characters	Makes retries safe
fulfilment	self or bureau	Print in your own print room, or have CardOffice print and deliver
deliverySku	string	A shipping.* item from your price book (bureau orders)
shippingAddress	string, max 500	Delivery address as text (bureau orders)
shippingContact	string, max 200	Name and phone for the courier

curl -sS -X POST "$CARDOFFICE_API/orders" \
  -H "Authorization: Bearer $CARDOFFICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cardHolderIds": ["0b5e4c1a-6a53-4d3b-9d45-3f6f6b2c9a10"],
    "priority": "standard",
    "idempotencyKey": "intake-2027-batch-0007"
  }'

Returns 201 and the order is created as a draft:

{
  "data": {
    "id": "a3e8e6f0-1c7f-4a52-8f0e-3d4f6b1d5c77",
    "orderNumber": "ACME-2027-0412",
    "cardCount": 1,
    "skipped": 0
  }
}

• skipped counts holders left out because they have no approved photo. If none of the holders has one, the call fails with 412 precondition_failed.
• A repeat with the same idempotencyKey returns 200 with the original result. If the first request is still being processed you receive 409 and should retry shortly.
• Creating an order locks the card template version it uses, so the design can no longer be edited.

Note

The submit field is accepted but does not submit the order. Orders always start as drafts. Submit explicitly with the PATCH below.

Get an order

GET/orders/{id}

Scope: orders:read. Returns the order with its fulfilment details (shippingAddress, carrier, trackingNumber, trackingUrl, shippedAt) and an items array. Each item has id, cardHolderId, status, sku, unitPrice, snapshot and createdAt.

Submit or cancel an order

PATCH/orders/{id}scope: orders:write

curl -sS -X PATCH "$CARDOFFICE_API/orders/$ORDER_ID" \
  -H "Authorization: Bearer $CARDOFFICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "submitted" }'

{
  "data": {
    "id": "a3e8e6f0-1c7f-4a52-8f0e-3d4f6b1d5c77",
    "orderNumber": "ACME-2027-0412",
    "status": "submitted",
    "updatedAt": "2027-02-01T03:00:00.000Z"
  }
}

Submitting renders the cards, notifies the print room and fires the order.submitted webhook, exactly as submitting in the portal does.

Status	When
422 validation_failed	status is anything other than submitted or cancelled
409 conflict	The move is not allowed from the current status
409 conflict	A bureau order can be cancelled through the API only while it is submitted. Once CardOffice has started producing it, cancellation is up to CardOffice