# Place an order

For designers.

Places an order at cost (production price, shipping and VAT) paid from your wallet, with any shortfall charged to your saved card, for example for a sale on your own website. Send an `Idempotency-Key` and reuse it on every retry: an order is created at most once. Follow the order with the `order.*` webhooks. To print your own file on a line instead of the variant's design, see Order with a custom file.

## What you need

-   `items` (array of object, required): What to order: `{ "variant": "var_...", "quantity": 1 }` per line. Each variant must be yours, active and approved.
-   `customer` (object, required): The recipient: `name`, `email` and optionally `phone`.
-   `shipping_address` (object, required): Where to ship: `line1`, `city`, `country_code` (ISO alpha-2) and optionally `line2`, `state`, `postal_code`.
-   `reference` (string): Your own reference for the order, for example your order number.
-   `idempotency_key` (string, required): A unique string for this attempt, for example a UUID. Send the same value when you retry, so the write happens once.

## Step 1: Create an order

[POST `/v2/orders`](https://public-api.dapi.digital/docs/reference/orders.md#create_order)

Create and pay the order. It comes back `paid` and goes to production. `payment_failed` (402) means no order was created: add or update the saved card in the dashboard, then retry with the same `Idempotency-Key`. `variant_not_orderable` (422) names a variant that is unknown, inactive or not approved.

**Parameters**

```json
{
  "header Idempotency-Key": "$inputs.idempotency_key"
}
```

**Request body**

```json
{
  "items": "$inputs.items",
  "customer": "$inputs.customer",
  "shipping_address": "$inputs.shipping_address",
  "reference": "$inputs.reference"
}
```

Succeeds when:

-   `$statusCode == 201`

Otherwise:

-   `retry_server_error`: retry after 5 seconds, at most 3 times, when `$statusCode >= 500`.
-   `payment_failed`: stop the workflow when `$statusCode == 402`.
-   `variant_not_orderable`: stop the workflow when `$statusCode == 422`.

Keeps for the next steps:

-   `order_id`: `$response.body#/id`
-   `number`: `$response.body#/number`
-   `status`: `$response.body#/status`
-   `total`: `$response.body#/charges/total`

## As a workflow file

The workflow returns:

-   `order_id`: `$steps.create_order.outputs.order_id`
-   `number`: `$steps.create_order.outputs.number`
-   `total`: `$steps.create_order.outputs.total`

Values starting with `$` are filled in as you go: `$inputs.x` is something you provide, `$steps.s.outputs.o` is a value an earlier step returned, and `$response.body#/path` a field of this response.

This recipe is the workflow `place_order` of [arazzo.json](https://public-api.dapi.digital/docs/arazzo.json), an [Arazzo 1.0](https://spec.openapis.org/arazzo/latest.html) document that tools and AI agents can follow step by step.

---

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