List Order Items
Changed onReturn 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.
Request
- Base URL: https://api.thanks.io/api/v2
- URL: https://api.thanks.io/api/v2/orders/{orderId}/items
- Auth: HTTP bearer
Path parameters
ID of the order whose items you want to list.
Query parameters
Number of items to return per page. Must be between 1 and 100.
Page of results to return.
Response
OK
Example response
{
"data": [
{
"id": 2668662,
"status": "In Transit",
"delivery_date": "2025-09-15",
"failure": "USPS lists address as 'no-stat' - address is unlikely to receive mail.",
"recipient": {
"name": "Tobias Example",
"company": "thanks.io",
"address": "12345 Main Street",
"address2": "Apartment 1",
"city": "Any Town",
"province": "KS",
"postal_code": "12345",
"country": "US",
"email": "tobias@example.com",
"phone": "5555555555",
"custom1": "Unique Info",
"custom2": "For example a product code or customer ID",
"absentee_address": "742 Evergreen Terrace, Springfield, IL 62704"
},
"giftcard": {
"brand": "amazonus",
"amount": 2500
},
"preview": {
"front": "https://cdn.thanks.io/orders/items/proofs/front-example.png",
"back": "https://cdn.thanks.io/orders/items/proofs/back-example.png"
},
"created_at": "2025-09-08T16:05:12.000000Z"
}
],
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 25,
"to": 1,
"total": 1
}
}Changes
- info
added the optional property
///to the response with the status
- info
- warning
removed the optional property
///from the response with the status
- warning