Skip to content
Last updated

🧾 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:

{
  "templateId": 12345
}

Response:

{
  "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:

{
  "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):

{
  "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:

{
  "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.
Previous page
Next page