# Creating an Order (/creating-an-order)



An **order** is a batch of direct mail generated from one of your templates and
addressed to a set of recipients. You create orders with a single call to
`POST /v1/order`, referencing a template you have already designed in the
LettrLabs app.

## Before you start [#before-you-start]

* A **public API key** — see [Authentication & API keys](/authentication-api-keys).
* A **template** built in the LettrLabs app. Its numeric **template ID** is what
  you pass as `templateId`.

## Create an order from a template [#create-an-order-from-a-template]

The only required field is `templateId`. The full request body — recipients,
mailing options, and template merge fields — is documented, field by field, on
the [`POST /v1/order`](/api-reference/orders/v1-order-post) reference page, where you can also
fire the request live with your own key.

```bash
curl -X POST https://app.lettrlabs.com/api/v1/order \
  -H "X-API-KEY: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": 12345
  }'
```

A successful call returns the created order. Keep the returned **order ID** — you
use it to manage recipients, pull proofs, and check out the order.

## Work with an order after it's created [#work-with-an-order-after-its-created]

Each of these is documented in full under [API Reference](/api-reference):

| Action                       | Endpoint                                                                                  |
| ---------------------------- | ----------------------------------------------------------------------------------------- |
| List orders                  | [`GET /v1/order`](/api-reference/orders/v1-order-get)                                     |
| Review an order's recipients | [`GET /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-get)       |
| Add or update recipients     | [`PUT /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-put)       |
| Remove recipients            | [`DELETE /v1/order/{id}/recipients`](/api-reference/orders/v1-order-id-recipients-delete) |
| Preview a proof              | [`GET /v1/order/{id}/proof`](/api-reference/orders/v1-order-id-proof-get)                 |
| Check out (confirm + pay)    | [`POST /v1/order/{id}/checkout`](/api-reference/orders/v1-order-id-checkout-post)         |
| Cancel an order              | [`DELETE /v1/order/{id}`](/api-reference/orders/v1-order-id-delete)                       |

## Idempotency [#idempotency]

Re‑sending the same `POST /v1/order` request creates a **new** order each time —
there is no automatic de‑duplication. If a request times out, fetch
`GET /v1/order` to check whether the order was created before retrying, so you
don't mail the same batch twice.