# Orders

Orders allocated to your farm, and moving them through their production statuses.

## Endpoints

-   [GET `/v1/print-farm/orders`](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#listPrintFarmOrders)
-   [GET `/v1/print-farm/orders/{orderId}`](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#getPrintFarmOrder)
-   [PATCH `/v1/print-farm/orders/{orderId}/status`](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#updatePrintFarmOrderStatus)

## The order object

### Attributes

-   `order_id` (string): Unique identifier for this order.
-   `status` (string): Current lifecycle stage of the order.
-   `designerName` (string): Name of the designer who created the ordered design.
-   `customer` (value): Recipient contact and shipping address details.
-   `extras` (value): Production requirements flagged for this order.
-   `tracking_number` (object, optional): Carrier tracking number, once the order has shipped.
-   `courier` (object, optional): Name of the shipping carrier, populated alongside the tracking number.
-   `external_order_id` (object, optional): Identifier of the order in an external system, when imported.
-   `items` (array of PrintFarmOrderItemDto): Line items that make up this order.
    -   `skuId` (string): Public identifier of the SKU (variant) for this line item (`sku_…`).
    -   `quantity` (number): Number of units ordered for this SKU.
    -   `sku` (value, optional): Present when `expand=items.sku` is requested. Inlines the SKU referenced by `skuId`.
-   `customLabels` (array 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.
    -   `productName` (string): Name of the product (listing) this custom label belongs to.
    -   `url` (string): Public URL of the custom label. May be an image or a PDF.
-   `created_at` (timestamp): ISO 8601 timestamp of when this order was created.
-   `allocated_at` (object, optional): 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**

```json
{
  "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 `/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

-   `page` (integer): 1-based page index.
    
    Range at least 1. Defaults to 1.
    
-   `page_size` (integer): Page size (max 100).
    
    Range 1 to 100. Defaults to 20.
    
-   `status` (string): Filter by order status. Accepts a comma-separated list to match any of several statuses.
-   `email` (string): Filter by customer email (case-insensitive partial match).
-   `phone` (string): Filter by customer phone number (case-insensitive partial match).
-   `designerName` (string): Filter by designer name (case-insensitive partial match).
-   `courier` (string): Filter by shipping carrier (case-insensitive partial match).
-   `created_after` (string): Return only orders created on or after this ISO 8601 timestamp.
-   `created_before` (string): Return only orders created on or before this ISO 8601 timestamp.
-   `allocated_after` (string): Return only orders allocated on or after this ISO 8601 timestamp.
-   `allocated_before` (string): Return only orders allocated on or before this ISO 8601 timestamp.
-   `expand` (string): 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.

### Returns 200 OK

Paginated list of orders allocated to the authenticated print farm.

Response attributes (ListPrintFarmOrdersResponseDto):

-   `orders` (array of PrintFarmOrderResponseDto): Orders on this page, sorted by creation date (newest first).
    
    Described in [the order object](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#farm_order_object).
    
-   `page` (number): Page number returned, matching the `page` query parameter.
    
    Range at least 1.
    
-   `page_size` (number): Number of items per page, matching the `page_size` query parameter.
    
    Range 1 to 100.
    
-   `total` (number): Total number of orders across all pages (after filters are applied).
    
    Range at least 0.
    

### 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](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/print-farm/orders" \
  -H "x-api-key: $DAPI_API_KEY"
```

**Response 200**

```json
{
  "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

-   `orderId` (string, required): The unique order identifier.

### Query parameters

-   `expand` (string): 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.

### Returns 200 OK

The requested order. Returns [the order object](https://public-api.dapi.digital/docs/reference/print-farm-orders.md#farm_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](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
curl "https://public-api.dapi.digital/v1/print-farm/orders/AP7K2M9X" \
  -H "x-api-key: $DAPI_API_KEY"
```

## 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

-   `orderId` (string, required): The unique order identifier.

### Request body

Status transition request body.

-   `status` (string, required): 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).
-   `tracking_number` (string): Shipping tracking number. Required when `status === "shipping"`. Persisted on the order and forwarded to the customer email + designer webhook.
-   `courier` (string): 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_name` (string): Human-readable carrier name. Required when `courier === "other"`. Stored on the order as the courier value (since no machine code exists).

### Returns 200 OK

Status updated (or unchanged if the request was a no-op).

Response attributes (UpdatePrintFarmOrderStatusResponseDto):

-   `status` (string): The newly persisted order status.

### 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](https://public-api.dapi.digital/docs/guides/print-farm-quickstart.md#errors).

**Request**

```bash
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 200**

```json
{
  "status": "in_production"
}
```

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/reference/print-farm-orders. Index of every page: https://public-api.dapi.digital/docs/llms.txt.
