Tickets
Support tickets: a conversation with its customer and the orders linked to it.
/ticketsRequires context:read. tRPC context.ticket.list, MCP list_tickets.
Returns stored tickets from the mailboxes you may read, latest message first, without contacting the store. Each item is a whole ticket, as GET /tickets/{ticketId} returns it.
A conversation has a ticket when the support classifier judged its latest customer message a support request. Messages classified as unclear or not support, not yet classified, or received before 29 September 2026 have none. A conversation removed from the inbox has no ticket. Tickets are updated every few minutes, not on every read; a refresh updates its ticket at once. The customer's order history and other conversations are read live with each page.
An empty items does not prove there are no support conversations: check mailbox sync, the support classifier and the key's connection access. A 400 for the cursor means starting again without cursor.
Authorization
apiKey In: header
Query Parameters
Page size, 1 to 100.
1 <= value <= 10020nextCursor from the previous page.
1 <= length <= 256Fields to leave out of each ticket. email leaves out customer.email.
items <= 1Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/tickets"{ "items": [ { "id": "string", "conversationId": "string", "customer": { "email": "string", "name": "string", "stores": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "customerSince": "string", "orders": 0, "amountSpent": "string", "currency": "string", "countryCode": "string", "checkedAt": "string" } ], "orderHistory": { "orders": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "orderId": "string", "orderName": "string", "createdAt": "string", "financialStatus": "string", "fulfillmentStatus": "string", "cancelledAt": "string", "total": { "amount": "string", "currency": "string" }, "items": [ { "title": "string", "variantTitle": "string", "sku": "string", "quantity": 0 } ] } ], "ordersOmitted": 0, "omittedForAccess": 0, "ordersSince": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "label": "string", "ordersSince": "string" } ], "totalSpend": [ { "currency": "string", "amount": "string" } ] }, "conversationHistory": { "conversations": [ { "conversationId": "string", "ticketId": "string", "subject": "string", "firstMessageAt": "string", "lastMessageAt": "string", "status": "open", "archivedAt": "string", "messageCount": 0 } ], "omitted": 0 } }, "conversation": { "subject": "string", "customerName": "string", "status": "open", "messageCount": 0, "lastMessageAt": "string", "archivedAt": "string" }, "orders": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "storeTimeZone": "string", "orderId": "string", "orderName": "string", "matchedBy": "email_lookup", "verified": true, "verificationMethod": "email", "lookup": { "state": "fetched", "fetchedAt": "string" }, "details": { "createdAt": "string", "cancelledAt": "string", "financialStatus": "string", "fulfillmentStatus": "string", "total": { "amount": "string", "currency": "string" }, "items": [ { "itemId": "string", "title": "string", "variantTitle": "string", "sku": "string", "quantity": 0, "unfulfilledQuantity": 0, "free": true, "discounts": [ { "kind": "code", "name": "string" } ] } ], "fulfillments": [ { "fulfillmentId": "string", "status": "string", "displayStatus": "string", "deliveredAt": "string", "estimatedDeliveryAt": "string", "inTransitSince": "string", "tracking": [ { "company": "string", "number": "string", "url": "string" } ], "providerStatus": { "source": "parcelpanel", "estimatedDeliveryText": "string", "status": "PENDING", "latestCheckpointAt": "string", "latestCheckpointDetail": "string" }, "events": [ { "status": "string", "happenedAt": "string", "message": "string", "city": "string", "province": "string", "country": "string", "estimatedDeliveryAt": "string" } ] } ] } } ], "unknowns": [ { "code": "no_order_for_email", "detail": "string", "retryAt": "string" } ], "subLabel": "delivery_status", "urgency": { "level": "urgent", "reasons": [ "health_or_safety" ] }, "checkedAt": "string", "createdAt": "string", "updatedAt": "string" } ], "nextCursor": "string"}/tickets/{ticketId}Requires context:read. tRPC context.ticket.get, MCP get_ticket.
Reads one stored ticket without contacting the store. Check each order's matchedBy, verified and details before relying on it: a 200 means the read succeeded, not that an order was found or recently checked.
An order's status is there once the store's orders have synced; its items stay empty until a store lookup has stored it or the shipping read below has read it. Fulfillments and items are read from the store every 30 minutes for orders on a ticket: until the order was first read, while a shipment is in transit, for three days after delivery, and whenever the order changes.
A 404 means no such ticket, or its mailbox is outside your access. A conversation id is not a ticket id.
Authorization
apiKey In: header
Path Parameters
A ticket id from GET /tickets.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidQuery Parameters
Fields to leave out of each ticket. email leaves out customer.email.
items <= 1Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/tickets/497f6eca-6276-4993-bfeb-53cbbbba6f08"{ "id": "string", "conversationId": "string", "customer": { "email": "string", "name": "string", "stores": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "customerSince": "string", "orders": 0, "amountSpent": "string", "currency": "string", "countryCode": "string", "checkedAt": "string" } ], "orderHistory": { "orders": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "orderId": "string", "orderName": "string", "createdAt": "string", "financialStatus": "string", "fulfillmentStatus": "string", "cancelledAt": "string", "total": { "amount": "string", "currency": "string" }, "items": [ { "title": "string", "variantTitle": "string", "sku": "string", "quantity": 0 } ] } ], "ordersOmitted": 0, "omittedForAccess": 0, "ordersSince": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "label": "string", "ordersSince": "string" } ], "totalSpend": [ { "currency": "string", "amount": "string" } ] }, "conversationHistory": { "conversations": [ { "conversationId": "string", "ticketId": "string", "subject": "string", "firstMessageAt": "string", "lastMessageAt": "string", "status": "open", "archivedAt": "string", "messageCount": 0 } ], "omitted": 0 } }, "conversation": { "subject": "string", "customerName": "string", "status": "open", "messageCount": 0, "lastMessageAt": "string", "archivedAt": "string" }, "orders": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "storeTimeZone": "string", "orderId": "string", "orderName": "string", "matchedBy": "email_lookup", "verified": true, "verificationMethod": "email", "lookup": { "state": "fetched", "fetchedAt": "string" }, "details": { "createdAt": "string", "cancelledAt": "string", "financialStatus": "string", "fulfillmentStatus": "string", "total": { "amount": "string", "currency": "string" }, "items": [ { "itemId": "string", "title": "string", "variantTitle": "string", "sku": "string", "quantity": 0, "unfulfilledQuantity": 0, "free": true, "discounts": [ { "kind": "code", "name": "string" } ] } ], "fulfillments": [ { "fulfillmentId": "string", "status": "string", "displayStatus": "string", "deliveredAt": "string", "estimatedDeliveryAt": "string", "inTransitSince": "string", "tracking": [ { "company": "string", "number": "string", "url": "string" } ], "providerStatus": { "source": "parcelpanel", "estimatedDeliveryText": "string", "status": "PENDING", "latestCheckpointAt": "string", "latestCheckpointDetail": "string" }, "events": [ { "status": "string", "happenedAt": "string", "message": "string", "city": "string", "province": "string", "country": "string", "estimatedDeliveryAt": "string" } ] } ] } } ], "unknowns": [ { "code": "no_order_for_email", "detail": "string", "retryAt": "string" } ], "subLabel": "delivery_status", "urgency": { "level": "urgent", "reasons": [ "health_or_safety" ] }, "checkedAt": "string", "createdAt": "string", "updatedAt": "string"}/tickets/{ticketId}/messagesRequires context:read. tRPC context.ticket.messages, MCP get_ticket_messages.
Returns the messages of the ticket's conversation that the mailbox still holds, oldest first. A message stored in two folders appears once; drafts and trash are left out. A body is cut at 20,000 characters.
If the messages add up to fewer than conversation.messageCount, some copies are no longer in the mailbox; that is not an error. A 400 Invalid cursor means a saved cursor stopped working after an update: start again without cursor.
Authorization
apiKey In: header
Path Parameters
A ticket id from GET /tickets.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidQuery Parameters
Page size, 1 to 50.
1 <= value <= 5020nextCursor from the previous page.
1 <= length <= 256Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/tickets/497f6eca-6276-4993-bfeb-53cbbbba6f08/messages"{ "conversation": { "id": "string", "subject": "string", "messageCount": 0, "firstMessageMissing": true }, "items": [ { "messageId": "string", "messageIdHeader": "string", "sentAt": "string", "author": "customer", "from": { "name": "string", "email": "string" }, "to": [ { "name": "string", "email": "string" } ], "body": "string", "hasHtml": true, "bodyTruncated": true, "normalized": { "parserVersion": "string", "currentText": "string", "quotedText": "string", "quotedTextTruncated": true, "signatureText": "string", "warnings": [ "string" ] }, "forwarded": true, "attachments": [ { "partId": "string", "filename": "string", "contentType": "string", "size": 0 } ] } ], "nextCursor": "string"}/tickets/{ticketId}/refreshRequires context:refresh, which includes context:read. tRPC context.ticket.refresh (a mutation), MCP refresh_ticket.
This operation may contact the store, as customer.findOrders also does. It runs the store lookups for the ticket's orders and its customer's email, stores the answers, fills the ticket's order links, and returns the ticket, so newly matched orders show at once. It never sends email or changes an order. Send no body, or {}.
- A lookup answered in the last five minutes is reused (
reused: true), not repeated, so refreshing again is safe. - A refresh starts at most five new order-number lookups and no new call after 45 seconds. Allow about 75 seconds.
- What it did not start is counted in
skipped; the next refresh continues from there.
A 200 does not mean the store answered: read refresh.state. provider_unavailable means wait before trying again; not_permitted means the key can read the mailbox but not the store, and nothing was checked; access_missing means no usable store is connected, or it has not granted the access needed.
A body is read before the permission check: one that is not valid JSON is 400 PARSE_ERROR, and one without content-type: application/json is 415. After a 500 the refresh may have stored lookups; read the ticket before refreshing again.
Authorization
apiKey In: header
Path Parameters
A ticket id from GET /tickets.
^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/tickets/497f6eca-6276-4993-bfeb-53cbbbba6f08/refresh"{ "refresh": { "state": "none", "checkedAt": "string", "attempts": [ { "orderName": "string", "state": "fresh", "checkedAt": "string", "reused": true } ], "customer": { "state": "fresh", "checkedAt": "string", "reused": true }, "storeCustomer": { "state": "fresh", "checkedAt": "string", "reused": true }, "providerCalls": 0, "skipped": 0 }, "ticket": { "id": "string", "conversationId": "string", "customer": { "email": "string", "name": "string", "stores": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "customerSince": "string", "orders": 0, "amountSpent": "string", "currency": "string", "countryCode": "string", "checkedAt": "string" } ], "orderHistory": { "orders": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "orderId": "string", "orderName": "string", "createdAt": "string", "financialStatus": "string", "fulfillmentStatus": "string", "cancelledAt": "string", "total": { "amount": "string", "currency": "string" }, "items": [ { "title": "string", "variantTitle": "string", "sku": "string", "quantity": 0 } ] } ], "ordersOmitted": 0, "omittedForAccess": 0, "ordersSince": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "label": "string", "ordersSince": "string" } ], "totalSpend": [ { "currency": "string", "amount": "string" } ] }, "conversationHistory": { "conversations": [ { "conversationId": "string", "ticketId": "string", "subject": "string", "firstMessageAt": "string", "lastMessageAt": "string", "status": "open", "archivedAt": "string", "messageCount": 0 } ], "omitted": 0 } }, "conversation": { "subject": "string", "customerName": "string", "status": "open", "messageCount": 0, "lastMessageAt": "string", "archivedAt": "string" }, "orders": [ { "storeConnectionId": "ccc7195b-c21e-4828-b08b-76e1da7e2a61", "storeTimeZone": "string", "orderId": "string", "orderName": "string", "matchedBy": "email_lookup", "verified": true, "verificationMethod": "email", "lookup": { "state": "fetched", "fetchedAt": "string" }, "details": { "createdAt": "string", "cancelledAt": "string", "financialStatus": "string", "fulfillmentStatus": "string", "total": { "amount": "string", "currency": "string" }, "items": [ { "itemId": "string", "title": "string", "variantTitle": "string", "sku": "string", "quantity": 0, "unfulfilledQuantity": 0, "free": true, "discounts": [ { "kind": "code", "name": "string" } ] } ], "fulfillments": [ { "fulfillmentId": "string", "status": "string", "displayStatus": "string", "deliveredAt": "string", "estimatedDeliveryAt": "string", "inTransitSince": "string", "tracking": [ { "company": "string", "number": "string", "url": "string" } ], "providerStatus": { "source": "parcelpanel", "estimatedDeliveryText": "string", "status": "PENDING", "latestCheckpointAt": "string", "latestCheckpointDetail": "string" }, "events": [ { "status": "string", "happenedAt": "string", "message": "string", "city": "string", "province": "string", "country": "string", "estimatedDeliveryAt": "string" } ] } ] } } ], "unknowns": [ { "code": "no_order_for_email", "detail": "string", "retryAt": "string" } ], "subLabel": "delivery_status", "urgency": { "level": "urgent", "reasons": [ "health_or_safety" ] }, "checkedAt": "string", "createdAt": "string", "updatedAt": "string" }}