---
title: "List Order Items"
method: GET
path: "/orders/{orderId}/items"
tags: ["Orders"]
---

# List Order Items

`GET /orders/{orderId}/items`

## Request

- Base URL: `https://api.thanks.io/api/v2`
- URL: `https://api.thanks.io/api/v2/orders/{orderId}/items`
- Auth: HTTP bearer

Return the individual mail pieces that make up an order, one entry per recipient, with that piece's delivery status, delivery date, QR scan count, failure reason and recipient address. Use this when you need per-piece detail; Track Order returns the same order as aggregate counts instead.

Results are paginated and ordered by item ID, ascending. The order must belong to the authenticated account.

For gift card orders each item also carries the gift card's `brand` and `amount`, plus `redeemed_at` and `invalidated_at` so you can see which cards have been claimed. To stop an unredeemed card from being redeemed, use Invalidate Gift Card.

The recipient's ten custom fields come back alongside the address, so the data you merged into the piece is available with it. Each item also carries a `preview` with the rendered front and back of that recipient's piece (and a PDF proof for letters and notecards), so you can see exactly what was mailed to each person. Previews are `null` until the piece has been rendered, shortly after the order is placed, and are never returned for gift card orders. Message content and per-item pricing are not part of this response; read those from the order itself.

## Path parameters

- `orderId` integer, required

## Query parameters

- `per_page` integer
- `page` integer

## Response `200`

OK

- object
  - `data` OrderItem[]
    - `id` integer: ID of the order item. This is the same identifier carried by order item webhook events.
    - `status` 'Processing' | 'Printed' | 'In Transit' | 'In Local Area' | 'Processed for Delivery' | 'Delivered' | 'Re-routed' | 'Returned to Sender' | 'Failed': Current delivery status of this piece.
    - `delivery_date` string, date, nullable: Date the piece was delivered, or `null` if it has not been delivered yet.
    - `scans` integer: Number of times this piece's QR code has been scanned.
    - `failure` string, nullable: Reason the piece could not be mailed or delivered, or `null` if there was no failure.
    - `recipient` object: Recipient details as submitted with the order — the mailing address plus the ten custom fields.
      - `name` string, nullable
      - `company` string, nullable
      - `address` string, nullable
      - `address2` string, nullable
      - `city` string, nullable
      - `province` string, nullable: State or Province
      - `postal_code` string, nullable
      - `country` string, nullable
      - `email` string, nullable
      - `phone` string, nullable
      - `custom1` string, nullable: Custom field 1 as submitted with the order.
      - `custom2` string, nullable: Custom field 2 as submitted with the order.
      - `custom3` string, nullable: Custom field 3 as submitted with the order.
      - `custom4` string, nullable: Custom field 4 as submitted with the order.
      - `custom5` string, nullable: Custom field 5 as submitted with the order.
      - `custom6` string, nullable: Custom field 6 as submitted with the order.
      - `custom7` string, nullable: Custom field 7 as submitted with the order.
      - `custom8` string, nullable: Custom field 8 as submitted with the order.
      - `custom9` string, nullable: Custom field 9 as submitted with the order.
      - `custom10` string, nullable: Custom field 10 as submitted with the order.
      - `absentee_address` string, nullable: The absentee (property) address as it was when this piece was sent, or null. Mail was delivered to `address`.
    - `giftcard` object, nullable: 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.
      - `brand` string: Brand code of the gift card.
      - `amount` integer: Face value of the gift card in cents.
      - `redeemed_at` string, date-time, nullable: When the recipient redeemed the gift card, or `null` if it has not been redeemed.
      - `invalidated_at` string, date-time, nullable: When the gift card was invalidated, or `null` if it has not been. An invalidated gift card can no longer be redeemed.
    - `preview` object: 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.
      - `front` string, uri, nullable: Image of the front of the piece. For a letter or windowless letter, the first page.
      - `back` string, uri, nullable: Image of the back of the piece. Postcards and magnacards only; `null` for other mailer types.
      - `pdf` string, uri, nullable: PDF proof of the full piece. Letters, windowless letters and notecards only; `null` for other mailer types.
    - `created_at` string, date-time
  - `links` Links
    - `first` string, nullable: URL of the first page of results
    - `last` string, nullable: URL of the last page of results
    - `prev` string, nullable: URL of the previous page of results
    - `next` string, nullable: URL of the next page of results
  - `meta` Meta
    - `current_page` integer: Current page number
    - `from` integer, nullable: Index of the first item on the current page
    - `last_page` integer: Total number of pages
    - `path` string: Base URL for the resource
    - `per_page` integer: Number of items per page
    - `to` integer, nullable: Index of the last item on the current page
    - `total` integer: Total number of items

## Other responses

- `401`: The access token is missing or invalid, or the order belongs to another account.
- `404`: Resource not found
- `422`: Validation failed on the query string — most commonly a `per_page` outside 1-100.

## Changes

- **2026-10-19** `bbe02ffe74f3`: 1 info
  - added the optional property `data/items/recipient/absentee_address` to the response with the `200` status
- **2026-10-18** `c10cfeb34552`: 1 warning
  - removed the optional property `data/items/recipient/absentee_address` from the response with the `200` status
- **2026-10-17** `10023a95b079`: 1 info
  - added the optional property `data/items/recipient/absentee_address` to the response with the `200` status
- **2026-10-09** `c76fc453c7ca`: 1 info
  - added the optional property `data/items/preview` to the response with the `200` status
- **2026-09-28** `f2de8d244db2`: 2 info
  - added the optional property `data/items/giftcard/invalidated_at` to the response with the `200` status
  - added the optional property `data/items/giftcard/redeemed_at` to the response with the `200` status

[Operation history](https://skmtc.dev/thanks-io/apis/thanks-io-api/changes/orders/:orderId/items/get.md)

---

[API](https://skmtc.dev/thanks-io/apis/thanks-io-api.md) · [All operations](https://skmtc.dev/thanks-io/apis/thanks-io-api/llms.txt) · [OpenAPI document](https://skmtc.dev/thanks-io/apis/thanks-io-api/revisions/c403fbf3dc0f?raw)