order-item

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/thanks-io/json-schema/thanks-io-order-item-schema.json",
  "title": "order-item",
  "description": "A single mail piece within an order — one recipient's postcard, letter, notecard, magnacard or gift card.",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/thanks-io-openapi.json#/components/schemas/order-item",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer",
      "description": "ID of the order item. This is the same identifier carried by order item webhook events."
    },
    "status": {
      "type": "string",
      "description": "Current delivery status of this piece.",
      "enum": [
        "Processing",
        "Printed",
        "In Transit",
        "In Local Area",
        "Processed for Delivery",
        "Delivered",
        "Re-routed",
        "Returned to Sender",
        "Failed"
      ]
    },
    "delivery_date": {
      "type": [
        "string",
        "null"
      ],
      "format": "date",
      "description": "Date the piece was delivered, or `null` if it has not been delivered yet."
    },
    "scans": {
      "type": "integer",
      "description": "Number of times this piece's QR code has been scanned."
    },
    "failure": {
      "type": [
        "string",
        "null"
      ],
      "description": "Reason the piece could not be mailed or delivered, or `null` if there was no failure."
    },
    "recipient": {
      "type": "object",
      "description": "Recipient details as submitted with the order — the mailing address plus the ten custom fields.",
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "company": {
          "type": [
            "string",
            "null"
          ]
        },
        "address": {
          "type": [
            "string",
            "null"
          ]
        },
        "address2": {
          "type": [
            "string",
            "null"
          ]
        },
        "city": {
          "type": [
            "string",
            "null"
          ]
        },
        "province": {
          "type": [
            "string",
            "null"
          ],
          "description": "State or Province"
        },
        "postal_code": {
          "type": [
            "string",
            "null"
          ]
        },
        "country": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": [
            "string",
            "null"
          ]
        },
        "phone": {
          "type": [
            "string",
            "null"
          ]
        },
        "custom1": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 1 as submitted with the order."
        },
        "custom2": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 2 as submitted with the order."
        },
        "custom3": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 3 as submitted with the order."
        },
        "custom4": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 4 as submitted with the order."
        },
        "custom5": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 5 as submitted with the order."
        },
        "custom6": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 6 as submitted with the order."
        },
        "custom7": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 7 as submitted with the order."
        },
        "custom8": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 8 as submitted with the order."
        },
        "custom9": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 9 as submitted with the order."
        },
        "custom10": {
          "type": [
            "string",
            "null"
          ],
          "description": "Custom field 10 as submitted with the order."
        },
        "absentee_address": {
          "type": [
            "string",
            "null"
          ],
          "description": "The absentee (property) address as it was when this piece was sent, or null. Mail was delivered to `address`."
        }
      }
    },
    "giftcard": {
      "type": [
        "object",
        "null"
      ],
      "description": "Present only on gift card orders. `null` when the gift card for this piece has not been issued yet. The redemption code, claim link and rendered card image are never returned.",
      "properties": {
        "brand": {
          "type": "string",
          "description": "Brand code of the gift card."
        },
        "amount": {
          "type": "integer",
          "description": "Face value of the gift card in cents."
        },
        "redeemed_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the recipient redeemed the gift card, or `null` if it has not been redeemed."
        },
        "invalidated_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "When the gift card was invalidated, or `null` if it has not been. An invalidated gift card can no longer be redeemed."
        }
      }
    },
    "preview": {
      "type": "object",
      "description": "The rendered proof of this recipient's piece, personalized with their name, address and custom fields. Each value is `null` until the piece has been rendered, which happens shortly after the order is placed, and stays `null` for a piece that failed before rendering. Absent on gift card orders: the rendered card carries the redemption code, so it is never returned.",
      "properties": {
        "front": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Image of the front of the piece. For a letter or windowless letter, the first page."
        },
        "back": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "Image of the back of the piece. Postcards and magnacards only; `null` for other mailer types."
        },
        "pdf": {
          "type": [
            "string",
            "null"
          ],
          "format": "uri",
          "description": "PDF proof of the full piece. Letters, windowless letters and notecards only; `null` for other mailer types."
        }
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}