Orders
Orders allocated to your farm, and moving them through their production statuses.
The order object
Attributes
- order_idstring
Unique identifier for this order.
- statusstring
Current lifecycle stage of the order.
- designerNamestring
Name of the designer who created the ordered design.
- customervalue
Recipient contact and shipping address details.
- extrasvalue
Production requirements flagged for this order.
- tracking_numberobjectOptional
Carrier tracking number, once the order has shipped.
- courierobjectOptional
Name of the shipping carrier, populated alongside the tracking number.
- external_order_idobjectOptional
Identifier of the order in an external system, when imported.
- itemsarray of PrintFarmOrderItemDto
Line items that make up this order.
- customLabelsarray of PrintFarmOrderCustomLabelDto
Custom labels set by the seller, one entry per distinct product (listing) in this order that has a custom label. Print farms must print each label and include it with the corresponding product in the shipment. Empty when no product in the order has a custom label.
- created_attimestamp
ISO 8601 timestamp of when this order was created.
- allocated_atobjectOptional
ISO 8601 timestamp of when this order was allocated to your print farm. The ship-by deadline is conventionally 5 days after this date. Null until the order is allocated.
{
"order_id": "AP7K2M9X",
"status": "allocated",
"designerName": "Jane Smith",
"customer": null,
"extras": null,
"tracking_number": "1Z999AA10123456784",
"courier": "ups",
"external_order_id": "EXT-10492",
"items": [
{
"skuId": "sku_aB3xKp9wFqZ7vM2nLpHt12cN8jR3sLkPm",
"quantity": 2,
"sku": null
}
],
"customLabels": [
{
"productName": "Dragon Figurine",
"url": "https://cdn.dapi.digital/labels/dragon-figurine.pdf"
}
],
"created_at": "2026-03-24T12:00:00.000Z",
"allocated_at": "2026-03-25T08:30:00.000Z"
}List orders allocated to your print farm
GET/
- Credentials
- An API key with the
READ_ORDERSorFULLpermission. - For
- Print farms
- Operation id
listPrintFarmOrders
Returns a paginated list of orders allocated to your print farm, sorted by creation date (newest first). Results can be narrowed with the status, email, phone, designerName, and courier filters. Requires an API key with the READ_ORDERS (or FULL) permission scope.
Query parameters
- pageinteger
1-based page index.
- page_sizeinteger
Page size (max 100).
- statusstring
Filter by order status. Accepts a comma-separated list to match any of several statuses.
- emailstring
Filter by customer email (case-insensitive partial match).
- phonestring
Filter by customer phone number (case-insensitive partial match).
- designerNamestring
Filter by designer name (case-insensitive partial match).
- courierstring
Filter by shipping carrier (case-insensitive partial match).
- created_afterstring
Return only orders created on or after this ISO 8601 timestamp.
- created_beforestring
Return only orders created on or before this ISO 8601 timestamp.
- allocated_afterstring
Return only orders allocated on or after this ISO 8601 timestamp.
- allocated_beforestring
Return only orders allocated on or before this ISO 8601 timestamp.
- expandstring
Comma-separated list of related resources to inline in the response. Allowed paths:
items.sku,items.sku.designs,items.sku.extras,items.sku.materials. Requesting a child path automatically enables its parent.
Returns200 OK
Paginated list of orders allocated to the authenticated print farm.
Responses
- 200
Paginated list of orders allocated to the authenticated print farm.
- 400
pageorpage_sizeis outside the allowed range. - 401
API key is missing or invalid.
- 403
The API key does not have the required permission scope.
- 429
Rate limit exceeded - wait until the window resets before retrying.
- 500
An unexpected error occurred on our side.
Errors use the print farm error body.
curl "https://public-api.dapi.digital/v1/print-farm/orders" \
-H "x-api-key: $DAPI_API_KEY"{
"orders": [
{
"order_id": "AP7K2M9X",
"status": "allocated",
"designerName": "Jane Smith",
"customer": null,
"extras": null,
"tracking_number": "1Z999AA10123456784",
"courier": "ups",
"external_order_id": "EXT-10492",
"items": [
{
"skuId": "sku_aB3xKp9wFqZ7vM2nLpHt12cN8jR3sLkPm",
"quantity": 2,
"sku": null
}
],
"customLabels": [
{
"productName": "Dragon Figurine",
"url": "https://cdn.dapi.digital/labels/dragon-figurine.pdf"
}
],
"created_at": "2026-03-24T12:00:00.000Z",
"allocated_at": "2026-03-25T08:30:00.000Z"
}
],
"page": 1,
"page_size": 20,
"total": 42
}Get one order allocated to your print farm
GET/
- Credentials
- An API key with the
READ_ORDERSorFULLpermission. - For
- Print farms
- Operation id
getPrintFarmOrder
Returns the order matching the given orderId, scoped to your print farm. Requires an API key with the READ_ORDERS (or FULL) permission scope.
Path parameters
- orderIdstringRequired
The unique order identifier.
Query parameters
- expandstring
Comma-separated list of related resources to inline in the response. Allowed paths:
items.sku,items.sku.designs,items.sku.extras,items.sku.materials. Requesting a child path automatically enables its parent.
Returns200 OK
The requested order. Returns the order object.
Responses
- 200
The requested order.
- 401
API key is missing or invalid.
- 403
The API key does not have the required permission scope.
- 404
No order with this
orderIdis allocated to your print farm. - 429
Rate limit exceeded - wait until the window resets before retrying.
- 500
An unexpected error occurred on our side.
Errors use the print farm error body.
curl "https://public-api.dapi.digital/v1/print-farm/orders/AP7K2M9X" \
-H "x-api-key: $DAPI_API_KEY"{
"order_id": "AP7K2M9X",
"status": "allocated",
"designerName": "Jane Smith",
"customer": null,
"extras": null,
"tracking_number": "1Z999AA10123456784",
"courier": "ups",
"external_order_id": "EXT-10492",
"items": [
{
"skuId": "sku_aB3xKp9wFqZ7vM2nLpHt12cN8jR3sLkPm",
"quantity": 2,
"sku": null
}
],
"customLabels": [
{
"productName": "Dragon Figurine",
"url": "https://cdn.dapi.digital/labels/dragon-figurine.pdf"
}
],
"created_at": "2026-03-24T12:00:00.000Z",
"allocated_at": "2026-03-25T08:30:00.000Z"
}Transition an order to a new status
PATCH/
- Credentials
- An API key with the
WRITE_ORDERSorFULLpermission. - For
- Print farms
- Operation id
updatePrintFarmOrderStatus
Moves an order belonging to your print farm to a new status. The print-farm transition matrix is intentionally tighter than the admin surface - only specific transitions are accepted, and any other change returns 400.
Currently supported:
paid → in_productionin_production → shipping- requirestracking_numberandcourier. Passcourieras a code fromGET /print-farm/courier-options(e.g.ups). For carriers not in the catalog, usecourier: "other"together withcourier_name; the order will be flagged for manual ShipStation sync.shipping → returnedandcompleted → returned- no body fields beyondstatus. Triggers an internal admin notification; the customer is NOT emailed and no webhook is delivered.
Same-status requests are a no-op. Side effects (designer webhook delivery, customer status email, ShipStation mark-shipped on shipping, admin manual-sync alert when applicable, returned-order admin notification) fire after the DB update and never fail the request - check your webhook + email logs to verify. Requires an API key with the WRITE_ORDERS (or FULL) permission scope.
Path parameters
- orderIdstringRequired
The unique order identifier.
Request body
Status transition request body.
- statusstringRequired
New order status.
in_productionis allowed frompaid;shippingis allowed fromin_production(requirestracking_number+courier);returnedis allowed fromshippingorcompleted(no body fields required).Possible valuesin_productionshippingreturned - tracking_numberstring
Shipping tracking number. Required when
status === "shipping". Persisted on the order and forwarded to the customer email + designer webhook. - courierstring
Carrier code from
GET /print-farm/courier-options(e.g.ups,fedex). Required whenstatus === "shipping". Whencourier === "other", also providecourier_nameand we will flag the order for manual sync (we cannot push it to ShipStation automatically). - courier_namestring
Human-readable carrier name. Required when
courier === "other". Stored on the order as the courier value (since no machine code exists).
Returns200 OK
Status updated (or unchanged if the request was a no-op).
Responses
- 200
Status updated (or unchanged if the request was a no-op).
- 400
Body validation failed, or the requested transition is not allowed from the order's current status.
- 401
API key is missing or invalid.
- 403
The API key does not have the required permission scope.
- 404
No order with this
orderIdis allocated to your print farm. - 429
Rate limit exceeded - wait until the window resets before retrying.
- 500
An unexpected error occurred on our side.
Errors use the print farm error body.
curl -X PATCH "https://public-api.dapi.digital/v1/print-farm/orders/AP7K2M9X/status" \
-H "x-api-key: $DAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "shipping",
"tracking_number": "1Z999AA10123456784",
"courier": "ups",
"courier_name": "Local Courier Ltd"
}'{
"status": "in_production"
}