# 🧾 How to Create and Submit an Order

This guide walks you through how to create and submit a print order via the LettrLabs API.

## 🔐 Prerequisites

- A valid LettrLabs API key (pass via the `Authorization` header).
- A design template ID available from within your account.
- Any custom merge fields or variable images used in your template should be known up front.


## ✅ Step 1: Create an Order from a Template

**Endpoint:**
`POST /v1/order`

**Description:**
Create a new order using an existing template.

**Request Body:**


```json
{
  "templateId": 12345
}
```

**Response:**


```json
{
  "orderId": 67890,
  "status": "Draft"
}
```

## 👥 Step 2: Add Recipients (Batch up to 1000)

**Endpoint:**
`PUT /v1/order/{id}/recipients:append`

**Notes:**

- You can send up to **1000 recipients per request**.
- Each recipient will have their address validated.
- You can include:
  - **Custom mail merge fields** (e.g., `{{FirstName}}`)
  - **Variable images** (`image1`–`image6`) using publicly accessible URLs
  - **Custom QR code URLs** with the `qrUrl` field


**Example Request:**


```json
{
  "recipients": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "address1": "123 Main St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "customField1": "Welcome!",
      "image1": "https://yourdomain.com/image1.jpg",
      "qrUrl": "https://example.com/custom-qr"
    }
  ]
}
```

**Response (summary):**


```json
{
  "totalRecipients": 1000,
  "deliverable": {
    "addressValidated": 980,
    "addressInvalidated": 20
  }
}
```

## 📦 Step 3: Preview Order Costs and Options

**Endpoint:**
`GET /v1/order/{id}/checkout`

**Use this to:**

- See line item costs
- Review production speed and postage options
- Estimate delivery windows


**Optional Query Params:**

- `PostageType`: `Standard` or `FirstClass`
- `ProductionSpeed`: `Normal`, `ExpeditedFaster`, `ExpeditedFastest`
- `HoldUntilDate`: future date in ISO 8601 format


## 🧾 Step 4: Finalize and Submit Order

**Endpoint:**
`POST /v1/order/{id}/checkout`

**Description:**
Locks the order and submits it to production. All recipients and designs are now final. You will be charged.

**Request Body Example:**


```json
{
  "postageType": "Standard",
  "productionSpeed": "Normal",
  "holdUntilDate": "2025-06-15T00:00:00Z"
}
```

**Note:** This call cannot be undone. Be sure your design and recipient list are correct.

## 🔍 Optional: Get Proofs for Review

**Endpoint:**
`GET /v1/order/{id}/proof`

- Returns a PDF proof for each recipient.
- You may preview merge results before checkout.
- You are not required to call this endpoint—**by checking out, you confirm the design is ready for print.**


## 🧠 Best Practices & Tips

- 🔁 Use **mail-merge fields** consistently. Ensure recipients include values for any merge tags in your design.
- 🖼️ For **variable images**, use HTTPS URLs for fields `image1` through `image6`.
- 🔗 Customize the **QR code** for each recipient using the `qrUrl` field.
- 🛑 Avoid resubmitting after `POST /checkout`—the order is locked and production starts immediately.