# Orders (API v1, deprecated)

Deprecated: API v1 keeps working for existing integrations but gets no new features. New integrations should use API v2 (https://public-api.dapi.digital/docs/guides/quickstart.md).

Orders placed from completed quotes, their shipping costs, and paying for them from the wallet.

## Endpoints

-   [GET `/v1/designer/orders`](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_listOrders)
-   [POST `/v1/designer/orders`](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_createOrder)
-   [GET `/v1/designer/orders/filaments`](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_listFilaments)
-   [GET `/v1/designer/orders/shipping/rates`](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_getShippingRates)
-   [POST `/v1/designer/orders/shipping/estimate`](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_estimateShipping)
-   [GET `/v1/designer/orders/{orderId}`](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_getOrderById)
-   [POST `/v1/orders/{orderId}/pay`](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_payOrder)

## The order object

### Attributes

-   `order_id` (string): Unique identifier for this order.
-   `status` (string): Current lifecycle stage of the order. Progresses from `pending` → `paid` → `in_production` → `shipping` → `completed`. May also be `rejected` or `returned`.
-   `delivery` (number): Flat delivery fee in USD, added on top of the item subtotals.
-   `order_total` (number): Grand total in USD, including all line items and the delivery fee.
-   `customer` (value): Recipient contact and shipping address details.
-   `items` (array of V1OrderItemPublicDto): Line items that make up this order, each derived from a completed quote.
    -   `quoteId` (string): The `publicId` of the quote this line item was derived from.
    -   `filaments` (array of string): Filament codes used for this item, one per colour slot, in slot order - the same order given when the order was placed. Single-colour items return a one-element array. See `GET /orders/filaments` for all codes.
    -   `individual_price` (number): Price per unit in USD, taken from the quote result.
    -   `quantity` (number): Number of units ordered for this line item.
    -   `total` (number): Line-item subtotal in USD (`individual_price` × `quantity`).
-   `tracking_number` (object, optional): Carrier tracking number. Populated once the order moves to `shipping` status.
-   `courier` (object, optional): Name of the shipping carrier (e.g. `ups`, `dhl`). Populated alongside `tracking_number`.
-   `created_at` (timestamp): ISO 8601 timestamp of when this order was placed.
-   `updated_at` (timestamp): ISO 8601 timestamp of the most recent change to this order (status update, tracking added, etc.).

**The order object**

```json
{
  "order_id": "AP7K2M9X",
  "status": "pending",
  "delivery": 10,
  "order_total": 133.4,
  "customer": null,
  "items": [
    {
      "quoteId": "dapi_a3f9b2c1e4",
      "filaments": [
        "PLA-GREEN",
        "PLA-RED"
      ],
      "individual_price": 12.34,
      "quantity": 5,
      "total": 61.7
    }
  ],
  "tracking_number": "1Z999AA10123456784",
  "courier": "ups",
  "created_at": "2026-03-24T12:00:00.000Z",
  "updated_at": "2026-03-24T12:05:00.000Z"
}
```

## List your orders

GET `/v1/designer/orders`

- **Credentials**: An API key with the `ORDER` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_listOrders`

Returns a paginated list of your orders, sorted by creation date (newest first). Each entry includes the current lifecycle status, shipping address, item breakdown, and tracking details when available. Use the `order_id` field to fetch full details via `GET /orders/:orderId`.

### 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.
    
-   `store_id` (string): Return only orders belonging to this store. Omit to return orders from every store on your account.

### Returns 200 OK

Paginated list of orders for the authenticated account.

Response attributes (V1ListOrdersResponseDto):

-   `items` (array of V1OrderPublicResponseDto): Orders on this page, sorted by creation date (newest first).
    
    Described in [the order object](https://public-api.dapi.digital/docs/reference/v1-orders#v1_order_public_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. Use this to determine whether more pages exist.
    
    Range at least 0.
    

### Responses

-   `200`: Paginated list of orders for the authenticated account.
-   `400`: `page` or `page_size` is outside the allowed range.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use order endpoints.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

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

**Response 200**

```json
{
  "items": [
    {
      "order_id": "AP7K2M9X",
      "status": "pending",
      "delivery": 10,
      "order_total": 133.4,
      "customer": null,
      "items": [
        {
          "quoteId": "dapi_a3f9b2c1e4",
          "filaments": [
            "PLA-GREEN",
            "PLA-RED"
          ],
          "individual_price": 12.34,
          "quantity": 5,
          "total": 61.7
        }
      ],
      "tracking_number": "1Z999AA10123456784",
      "courier": "ups",
      "created_at": "2026-03-24T12:00:00.000Z",
      "updated_at": "2026-03-24T12:05:00.000Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 42
}
```

## Create an order from completed quotes

POST `/v1/designer/orders`

- **Credentials**: An API key with the `ORDER` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_createOrder`

Places a new order by combining one or more completed quotes. Each item references a quote by its `publicId` and specifies the filament and quantity to produce.

**Prerequisites:**

-   All referenced quotes must have `status` equal to `DONE`.
-   All filament codes must be valid - retrieve available codes from `GET /orders/filaments`.
-   At least one item is required.
-   Each item lists its filaments in `filaments`, one code per colour slot in slot order; a single-colour design sends a one-element array.

**Multi-colour items:** `filaments` lists one code per colour slot in the design's own extruder order, so `["PLA-GREEN","PLA-RED"]` and `["PLA-RED","PLA-GREEN"]` order different products. Each distinct combination becomes its own SKU; repeating the same quote with the same combination reuses it.

The order is created with status `pending`. Use `POST /orders/:orderId/pay` to pay for it and move it into production.

### Request body

-   `customer` (value, required): Recipient contact and shipping address. All nested fields are required.
-   `items` (array of V1OrderItemDto, required): One or more items to include in the order. Each item references a completed quote and specifies a filament and quantity. At least one item is required.
    -   `quoteId` (string, required): The `publicId` of a completed quote (`status` must be `DONE`). Each quote may appear at most once per order.
    -   `filaments` (array of string, required): Filament codes for this item, one per colour slot, **in slot order**. Slot order is the design's own extruder order, so `["PLA-GREEN","PLA-RED"]` and `["PLA-RED","PLA-GREEN"]` are different products. Give a single-element array for a single-colour design. Retrieve valid codes from `GET /orders/filaments`.
    -   `quantity` (number, required): Number of units to produce for this item. Minimum is `1`.
        
        Range at least 1.
        
-   `store_id` (string): The store this order belongs to. Required once your account has at least one store. Every quote referenced in `items` must belong to this same store.
-   `customer_notes` (string): Optional notes for the order (e.g. delivery instructions).
-   `checkout_link` (boolean): When `true`, a hosted Stripe Checkout URL is generated and returned in the response as `checkout_link`. The customer can open this URL in a browser to pay for the order. The order status will automatically advance to `paid` once payment is completed via Stripe. Requires `checkout_success_url` and `checkout_cancel_url`.
    
    Defaults to false.
    
-   `checkout_success_url` (string): URL to redirect the customer to after a successful Stripe Checkout payment. Required when `checkout_link` is `true`. You may include `{CHECKOUT_SESSION_ID}` as a placeholder - Stripe will substitute it with the actual session ID.
-   `checkout_cancel_url` (string): URL to redirect the customer to if they cancel the Stripe Checkout flow. Required when `checkout_link` is `true`.

### Returns 201 Created

Order created with status `pending`. Pay with `POST /orders/:orderId/pay` to proceed.

Response attributes (V1CreateOrderResponseDto):

-   `orderId` (string): Unique identifier for the newly created order. Use this with `POST /orders/:orderId/pay` to pay for the order.
-   `status` (string): Initial status of the order. Always `pending` on creation - pay with `POST /orders/:orderId/pay` to advance it into production.
-   `delivery` (number): Flat delivery fee in USD.
-   `order_total` (number): Grand total in USD, including all line items and the delivery fee.
-   `items` (array of V1OrderItemResponseDto): Line items included in this order with their final pricing.
    -   `quoteId` (string): The `publicId` of the quote this line item was created from.
    -   `individual_price` (number): Price per unit in USD, taken from the quote result.
    -   `quantity` (number): Number of units ordered for this line item.
    -   `total` (number): Line-item subtotal in USD (`individual_price` × `quantity`).
-   `checkout_link` (string, optional): Hosted Stripe Checkout URL. Only present when `checkout_link: true` was passed in the request. Redirect your customer to this URL to complete payment in the browser.

### Responses

-   `201`: Order created with status `pending`. Pay with `POST /orders/:orderId/pay` to proceed.
-   `400`: Request body failed validation, a filament code is unrecognised, or a referenced quote does not have `status` `DONE`.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use order endpoints.
-   `404`: One or more referenced quote `publicId` values were not found for your account.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl -X POST "https://public-api.dapi.digital/v1/designer/orders" \
  -H "x-api-key: $DAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer": null,
  "items": [
    {
      "quoteId": "dapi_a3f9b2c1e4",
      "filaments": [
        "PLA-GREEN",
        "PLA-RED"
      ],
      "quantity": 5
    }
  ],
  "store_id": "str_9f2c4a7b13d84e0fa6c5b8e21d47a903",
  "customer_notes": "Please leave at the door.",
  "checkout_link": false,
  "checkout_success_url": "https://yourstore.com/orders/success?ref={CHECKOUT_SESSION_ID}",
  "checkout_cancel_url": "https://yourstore.com/orders/cancelled"
}'
```

**Response 201**

```json
{
  "orderId": "AP7K2M9X",
  "status": "pending",
  "delivery": 10,
  "order_total": 133.4,
  "items": [
    {
      "quoteId": "dapi_a3f9b2c1e4",
      "individual_price": 12.34,
      "quantity": 5,
      "total": 61.7
    }
  ],
  "checkout_link": "https://checkout.stripe.com/c/pay/cs_test_..."
}
```

## List available filaments

GET `/v1/designer/orders/filaments`

- **Credentials**: An API key with the `ORDER` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_listFilaments`

Returns all filament options currently available for ordering. Use the `code` value (e.g. `PLA-GREEN`) in the `filaments` array of each item when creating an order via `POST /orders`.

### Returns 200 OK

All filaments available for use in orders.

Response attributes (V1ListFilamentsResponseDto):

-   `items` (array of V1FilamentResponseDto): All filaments currently available for ordering.
    -   `code` (string): Unique filament identifier to use in the `filament` field when creating an order. Format: `{MATERIAL}-{COLOR}` in uppercase with hyphens (e.g. `PLA-GREEN`, `PETG-BLACK`).
    -   `name` (string): Human-readable display name of the filament, suitable for use in a UI.
    -   `color` (object): Color of the filament in lowercase English. `null` when the filament is multi-color or the color is unspecified.

### Responses

-   `200`: All filaments available for use in orders.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use order endpoints.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

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

**Response 200**

```json
{
  "items": [
    {
      "code": "PLA-GREEN",
      "name": "PLA Green",
      "color": "green"
    }
  ]
}
```

## Get the shipping rate card

GET `/v1/designer/orders/shipping/rates`

- **Credentials**: An API key with the `ORDER` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_getShippingRates`

Returns every shipping zone, the countries it covers as ISO 3166-1 alpha-2 codes, and the price of the first item in each weight tier plus each additional item.

**How a parcel is priced:**

-   The tier comes from the HEAVIEST single item, not the summed weight of the order. Two small items ship as one Small plus one additional item, not as a Medium.
-   Items under `extra_small_max_grams` are exempt from `additional_item_price`.
-   A destination no zone lists falls to the zone with `catch_all` set.
-   An order that cannot be rated at all is charged `flat_rate`.

Use `POST /orders/shipping/estimate` to price a specific order rather than deriving it.

### Returns 200 OK

The active rate card.

Response attributes (V1ShippingRatesResponseDto):

-   `zones` (array of V1ShippingZoneResponseDto)
    -   `zone` (string): Zone identifier.
    -   `label` (string): Human-readable zone name.
    -   `countries` (array of string): ISO 3166-1 alpha-2 codes covered by this zone. Empty when `catch_all` is true.
    -   `unmapped_countries` (array of string): Country names on the zone that do not map to an ISO code. Normally empty; a destination listed here still matches at order time but cannot be expressed as a code.
    -   `catch_all` (boolean): Whether this is the fallback zone, used for any destination no other zone lists.
    -   `small_first_price` (number): First item, Small tier.
    -   `medium_first_price` (number): First item, Medium tier.
    -   `large_first_price` (number): First item, Large tier.
    -   `additional_item_price` (number): Charged for every billable item after the first. Extra-small items are exempt.
-   `tiers` (array of V1ShippingTierResponseDto): Weight bands a parcel is priced at. The tier is set by the HEAVIEST single item, not by the summed weight of the order.
    -   `tier` (string)
        
        Possible values: `small`, `medium`, `large`.
        
    -   `max_grams` (object): Upper bound in grams, inclusive. `null` on the largest tier.
-   `extra_small_max_grams` (number): Items under this weight are exempt from `additional_item_price`.
-   `flat_rate` (number): Charged when an order cannot be rated - an unweighed design, or a destination no zone covers.

### Responses

-   `200`: The active rate card.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use order endpoints.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

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

**Response 200**

```json
{
  "zones": [
    {
      "zone": "EU",
      "label": "European Union",
      "countries": [
        "AT",
        "BE",
        "DE",
        "FR"
      ],
      "unmapped_countries": [],
      "catch_all": false,
      "small_first_price": 4.5,
      "medium_first_price": 7.9,
      "large_first_price": 14,
      "additional_item_price": 1
    }
  ],
  "tiers": [
    {
      "tier": "small",
      "max_grams": 600
    }
  ],
  "extra_small_max_grams": 100,
  "flat_rate": 10
}
```

## Estimate shipping for an order

POST `/v1/designer/orders/shipping/estimate`

- **Credentials**: An API key with the `ORDER` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_estimateShipping`

Prices shipping for a set of quotes and a destination, without placing an order. Runs the same weigh -> tier -> price steps order creation does, against the same rate card, so the number returned is the number the order will be charged.

Filaments are not accepted: colour does not change what a parcel weighs.

A destination that cannot be rated against the card is still priced - `shipping` is always what the order will be charged - but comes back with `zone` and `tier` null.

### Request body

-   `country` (string, required): 2-letter ISO 3166-1 alpha-2 destination code, uppercase.
-   `items` (array of V1EstimateShippingItemDto, required): Items to ship. Filaments are not needed: colour does not change what a parcel weighs.
    -   `quoteId` (string, required): The `publicId` of a completed quote (`status` must be `DONE`).
    -   `quantity` (number, required): Units of this quote.
        
        Range at least 1.
        

### Returns 200 OK

The shipping cost this order would be charged.

Response attributes (V1EstimateShippingResponseDto):

-   `country` (string)
-   `zone` (object): Null when the flat rate applied.
-   `zone_label` (object)
-   `tier` (object): Tier the parcel was priced at - the heaviest single item.
-   `item_count` (number): Units in the order.
-   `billable_item_count` (number): Units charged `additional_item_price` (after the first). Excludes extra-small items, so this can be 0.
-   `extra_small_items` (boolean): Whether any item was light enough to be exempt from the per-item charge.
-   `shipping` (number): Shipping cost in USD. This is what the order will be charged. `zone` and `tier` are null when the destination could not be rated against the card.

### Responses

-   `200`: The shipping cost this order would be charged.
-   `400`: Request body failed validation, or a quote has not finished slicing.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use order endpoints.
-   `404`: One or more quotes do not exist for your account.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl -X POST "https://public-api.dapi.digital/v1/designer/orders/shipping/estimate" \
  -H "x-api-key: $DAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "country": "DE",
  "items": [
    {
      "quoteId": "dapi_a3f9b2c1e4",
      "quantity": 5
    }
  ]
}'
```

**Response 200**

```json
{
  "country": "DE",
  "zone": "EU",
  "zone_label": "European Union",
  "tier": "small",
  "item_count": 5,
  "billable_item_count": 0,
  "extra_small_items": true,
  "shipping": 4.5
}
```

## Get one order

GET `/v1/designer/orders/{orderId}`

- **Credentials**: An API key with the `ORDER` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_getOrderById`

Returns the order matching the given `orderId`. Includes current status, recipient details, item breakdown, and tracking information once the order ships.

## Webhook Notifications

When an order status changes to `paid`, `in_production`, `shipping`, or `completed`, we send an HTTP `POST` to your configured webhook URL (set via the dashboard). Each notification is signed - verify the `X-Dapi-Webhook-Signature` header using your webhook secret.

### Webhook Payload Shape

**JSON**

```json
{
  "event": "order.in_production",
  "order": {
    "order_id": "AP7K2M9X",
    "status": "in_production",
    "tracking_number": null,
    "courier": null
  },
  "timestamp": "2026-03-25T12:05:00.000Z"
}
```

### Expected Response

Return any `2xx` status code to acknowledge receipt. We retry on non-2xx responses.

### Path parameters

-   `orderId` (string, required): The unique order identifier returned when the order was created.

### Returns 200 OK

The requested order object. Returns [the order object](https://public-api.dapi.digital/docs/v1/reference/orders.md#v1_order_public_object).

### Responses

-   `200`: The requested order object.
-   `401`: API key is missing or invalid.
-   `403`: The API key does not have permission to use order endpoints.
-   `404`: No order with this `orderId` exists for your account.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

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

## Pay for an order using wallet balance

POST `/v1/orders/{orderId}/pay`

- **Credentials**: An API key with the `ORDER` or `FULL` permission.

- **For**: Designers

- **Operation id**: `v1_payOrder`

Pay for a pending order. Three payment methods are available:

-   **`wallet`**: Debit the order amount directly from your wallet balance. Fails if the balance is insufficient.
-   **`wallet_auto`**: If wallet balance is insufficient, automatically top up from your saved card to the configured auto-topup amount, then debit.
-   **`wallet_difference`**: If wallet balance is insufficient, automatically top up only the deficit from your saved card, then debit.

Both `wallet_auto` and `wallet_difference` require a saved card on your wallet.

This endpoint is idempotent - calling it on an already-paid order returns `409 Conflict`.

### Path parameters

-   `orderId` (string, required): The unique order identifier returned when the order was created.

### Request body

-   `paymentMethod` (string, required):
    
    How to fund the payment.
    
    -   `wallet` - deduct the full order amount from your wallet. Fails with `400` if the balance is insufficient.
    -   `wallet_auto` - if your wallet balance is too low, top it up from your saved card to the configured auto-topup target, then deduct. Requires a saved card.
    -   `wallet_difference` - if your wallet balance is too low, charge only the deficit to your saved card, then deduct. Requires a saved card.
    

### Returns 200 OK

Payment successful. Order status is now `paid`.

Response attributes (V1PayOrderResponseDto):

-   `orderId` (string): Identifier of the order that was paid.
-   `status` (string): Order status after successful payment. Always `paid` on a `200` response.
-   `topupAmountUsd` (number): Amount in USD charged to your saved card as a wallet top-up. `0` when no top-up was needed because the wallet already had sufficient funds.
-   `walletDebitedUsd` (number): Amount in USD deducted from your wallet to settle the order.

### Responses

-   `200`: Payment successful. Order status is now `paid`.
-   `400`: Wallet balance is insufficient and no auto-topup is configured, or no saved card is on file for the selected payment method.
-   `401`: API key is missing or invalid.
-   `402`: Card charge failed. The payment could not be confirmed - verify your saved card details or add a new card via the dashboard.
-   `403`: The API key does not have permission to use order endpoints, or this order belongs to a different account.
-   `404`: No order with this `orderId` exists for your account.
-   `409`: The order has already been paid. No further action is needed.
-   `429`: Rate limit exceeded - wait until the window resets before retrying.
-   `500`: An unexpected error occurred on our side.

Errors use [the v1 error body](https://public-api.dapi.digital/docs/v1/reference.md#errors).

**Request**

```bash
curl -X POST "https://public-api.dapi.digital/v1/orders/AP-A1B2C3/pay" \
  -H "x-api-key: $DAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "paymentMethod": "wallet"
}'
```

**Response 200**

```json
{
  "orderId": "AP-A1B2C3",
  "status": "paid",
  "topupAmountUsd": 50,
  "walletDebitedUsd": 25.5
}
```

---

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