Orders

View as Markdown

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.

The order object
{
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  ,
  
}

List orders allocated to your print farm

GET/v1/print-farm/orders

Credentials
An API key with the READ_ORDERS or FULL permission.
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.

    Range at least 1. Defaults to 1.
  • page_sizeinteger

    Page size (max 100).

    Range 1 to 100. Defaults to 20.
  • 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

    page or page_size is 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.

GET/v1/print-farm/orders
curl "https://public-api.dapi.digital/v1/print-farm/orders" \
  -H "x-api-key: $DAPI_API_KEY"
Response
{
  "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/v1/print-farm/orders/{orderId}

Credentials
An API key with the READ_ORDERS or FULL permission.
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 orderId is 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.

GET/v1/print-farm/orders/{orderId}
curl "https://public-api.dapi.digital/v1/print-farm/orders/AP7K2M9X" \
  -H "x-api-key: $DAPI_API_KEY"
Response
{
  "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/v1/print-farm/orders/{orderId}/status

Credentials
An API key with the WRITE_ORDERS or FULL permission.
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_production
  • in_production → shipping - requires tracking_number and courier. Pass courier as a code from GET /print-farm/courier-options (e.g. ups). For carriers not in the catalog, use courier: "other" together with courier_name; the order will be flagged for manual ShipStation sync.
  • shipping → returned and completed → returned - no body fields beyond status. 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_production is allowed from paid; shipping is allowed from in_production (requires tracking_number + courier); returned is allowed from shipping or completed (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 when status === "shipping". When courier === "other", also provide courier_name and 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 orderId is 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.

PATCH/v1/print-farm/orders/{orderId}/status
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"
}'
Response
{
  "status": "in_production"
}