Query Orders

Retrieve your TPX purchase orders — status, fulfillment, and shipment tracking — with flexible filtering. Results are automatically scoped to your authenticated partner account.

query getMyTpxOrders($input: GetMyTpxOrdersInput!)

Basic Query

query {
  getMyTpxOrders(input: { pagination: { limit: 20, offset: 0 } }) {
    orders {
      id
      status
      quantity
      totalAmountCents
      transferDeadline
      missedDeadline
      createdAt
    }
    pagination { totalCount hasNextPage }
  }
}

Filtering

All filters are optional and combine with AND. Look up a single order by any reference you hold, or filter a list by status, date, asset, or tracking. See Input Parameters for the full list.

# Look up a single order by its order ID
query {
  getMyTpxOrders(input: { orderId: "84b60033-6b5e-4ea2-946d-f1670091746d" }) {
    orders {
      id
      status
      quantity
      totalAmountCents
      createdAt
    }
    pagination { totalCount }
  }
}

# Or by a reference from a webhook / your own system
query { getMyTpxOrders(input: { instantCashOfferId: "8801e2de-..." }) { orders { id status } } }
query { getMyTpxOrders(input: { externalReferenceId: "your-tracking-id" }) { orders { id status } } }

# Filter a list by status + date range
query {
  getMyTpxOrders(input: {
    statuses: ["COMPLETED"]
    createdAfter: "2026-01-01T00:00:00Z"
    createdBefore: "2026-01-31T23:59:59Z"
    pagination: { limit: 50, offset: 0 }
  }) {
    orders { id status totalAmountCents createdAt }
    pagination { totalCount hasNextPage }
  }
}

Shipment Tracking

Shipment status and carrier tracking are returned through the transfers relationship — not as top-level Order fields, so you must select them explicitly. An order can have multiple shipping labels (one per parcel when a large order ships in several boxes), so shippingLabels is a list.

query {
  getMyTpxOrders(input: { pagination: { limit: 20, offset: 0 } }) {
    orders {
      id
      status
      transfers {
        status                   # transfer-level fulfillment status (enum)
        shippingLabels {         # one entry per parcel
          trackingCode
          carrier
          currentStatus          # label status (enum)
          estimatedDeliveryDate
          data {
            tracker {
              status             # live carrier status
              statusDetail
              publicUrl          # carrier-hosted tracking page
              estDeliveryDate
              trackingDetails {  # scan-by-scan history
                message
                status
                datetime
                trackingLocation
              }
            }
          }
        }
      }
    }
    pagination { totalCount hasNextPage }
  }
}

Example response — a 7-unit order split into two boxes, each with its own tracking:

{
  "data": {
    "getMyTpxOrders": {
      "orders": [
        {
          "id": "84b60033-6b5e-4ea2-946d-f1670091746d",
          "status": "PENDING",
          "transfers": [
            {
              "status": "SHIPPED",
              "shippingLabels": [
                {
                  "trackingCode": "1Z1493G20319970373",
                  "carrier": "UPSDAP",
                  "currentStatus": "IN_TRANSIT",
                  "estimatedDeliveryDate": "2026-06-04T00:00:00Z",
                  "data": {
                    "tracker": {
                      "status": "in_transit",
                      "statusDetail": "status_update",
                      "publicUrl": "https://track.easypost.com/djE6dHJrXzAzYjk1ZGM4...",
                      "estDeliveryDate": "2026-06-04T00:00:00Z",
                      "trackingDetails": [
                        { "message": "Drop-Off", "status": "in_transit", "datetime": "2026-06-02T14:55:00Z", "trackingLocation": { "city": "Chicago", "state": "IL", "zip": null } },
                        { "message": "Shipper created a label, UPS has not received the package yet.", "status": "pre_transit", "datetime": "2026-06-02T14:32:25Z", "trackingLocation": { "city": null, "state": null, "zip": null } }
                      ]
                    }
                  }
                },
                {
                  "trackingCode": "1Z1493G20337785058",
                  "carrier": "UPSDAP",
                  "currentStatus": "IN_TRANSIT",
                  "estimatedDeliveryDate": "2026-06-04T00:00:00Z",
                  "data": {
                    "tracker": {
                      "status": "in_transit",
                      "publicUrl": "https://track.easypost.com/djE6dHJrXzM4MDJjOTNi...",
                      "estDeliveryDate": "2026-06-04T00:00:00Z",
                      "trackingDetails": [
                        { "message": "Drop-Off", "status": "in_transit", "datetime": "2026-06-02T14:55:00Z", "trackingLocation": { "city": "Chicago", "state": "IL", "zip": null } }
                      ]
                    }
                  }
                }
              ]
            }
          ]
        }
      ],
      "pagination": { "totalCount": 859, "hasNextPage": true, "limit": 20, "offset": 0 }
    }
  }
}

Notes

Multiple labels per order — iterate shippingLabels. A large order splits across boxes, each with its own trackingCode, carrier, currentStatus, and history.
Status is per-box, not per-order — with a split shipment one box can be DELIVERED while another is PRE_TRANSIT. Use transfers[].status for the rollup and shippingLabels[].currentStatus / tracker.status for the granular truth.
Skip placeholder labels — a transfer may include an entry with trackingCode: null and currentStatus: "UNKNOWN". Filter these out.
Carrier status is a passthrough string — tracker.status and trackingDetails[].status are raw carrier values ("in_transit", "delivered", sometimes "unknown"), not enums. The typed enums are transfers[].status and shippingLabels[].currentStatus.
Physical shipments only — shippingLabels / tracker are null for digital/ticket transfers and for labels not yet generated (AWAITING_SHIPMENT, PENDING_LABEL_GENERATION).
Freshness — history reflects the last carrier webhook stored on the label; it is not fetched live from the carrier on each query.

Input Parameters

Find a single order

Any one of these returns the matching order. IDs come from webhooks or your own records.

Field	Type	Description
`conversationId`	ID	TPX conversation ID from webhooks
`instantCashOfferId`	ID	ICO ID from webhooks
`orderId`	ID	Direct order ID
`transferId`	ID	Order associated with this transfer
`externalReferenceId`	String	Your tracking ID from the conditional bid

Filter a list

Field	Type	Description
`statuses`	[String!]	Order statuses (see values)
`transferStatuses`	[String!]	Transfer statuses (see values)
`createdAfter` / `createdBefore`	DateTime	Creation date range (inclusive)
`updatedAfter` / `updatedBefore`	DateTime	Update date range (inclusive)
`trackingCode`	String	Shipment tracking code
`recipientAddressId`	ID	Saved recipient address ID
`assetConfigName`	String	Asset configuration name
`assetTypeIds`	[ID!]	One or more asset type IDs
`minQuantity` / `maxQuantity`	Int	Order quantity range (inclusive)
`pagination`	SimplePaginationInput	`{ limit, offset }` (default limit 20, max 100)

Response Fields

Order

type Order {
  id: ID!
  status: OrderStatus!
  buyerAccountId: ID!
  sourceType: String!
  sourceId: ID!
  quantity: Int!
  totalAmountCents: Int!
  transferDeadline: DateTime!
  missedDeadline: Boolean!
  createdAt: DateTime!
  updatedAt: DateTime!
  data: JSON

  # Relationships — select explicitly
  transfers: [Transfer!]!          # fulfillment + shipment tracking
  disputes: [OfferDisputeDetails!]!
  returns: [Return!]!

  # Asset block — same shape as the webhook payloads
  assetPayload: TpxAssetPayload
}

Asset Payload

assetPayload carries the same asset block as the TPX webhooks (asset_type, external_ids, asset_details, config_details, item_details), so you get an identical shape whether you receive an order via webhook or fetch it here. The detail objects are asset-type-specific and returned as JSON — see Webhook Messages and Asset Types for the fields per asset type.

type TpxAssetPayload {
  assetType: String!     # readable type, e.g. "TICKET", "SEALED_TCG", "LEGO"
  externalIds: JSON      # platform identifiers
  assetDetails: JSON     # asset-level details
  configDetails: JSON    # configuration-level details
  itemDetails: JSON      # item-level details (keys, quantity, condition, etc.)
}

query {
  getMyTpxOrders(input: { pagination: { limit: 20, offset: 0 } }) {
    orders {
      id
      status
      assetPayload {
        assetType
        externalIds
        assetDetails
        configDetails
        itemDetails
      }
    }
  }
}

note

The JSON inside the detail objects uses snake_case field names — identical to the webhook payload — even though the GraphQL wrapper fields are camelCase.

Transfer & ShippingLabel

type Transfer {
  id: ID!
  status: TransferStatus!           # fulfillment status (enum)
  shippingLabels: [ShippingLabel!]  # one per parcel; null for digital/ticket
  deadline: DateTime
  missedDeadline: Boolean
  completedAt: DateTime
}

type ShippingLabel {
  trackingCode: String
  carrier: String                       # e.g. "UPSDAP", "USPS"
  currentStatus: ShippingLabelStatus!   # label status (enum)
  estimatedDeliveryDate: DateTime
  data: ShippingLabelData!              # contains `tracker`
}

type Tracker {                          # data.tracker
  status: String                        # live carrier status (string passthrough)
  statusDetail: String
  estDeliveryDate: String
  publicUrl: String                     # carrier-hosted tracking page
  signedBy: String
  trackingDetails: [TrackingDetail!]!   # scan-by-scan history
}

type TrackingDetail {
  message: String                       # e.g. "Arrived at Regional Facility"
  status: String
  datetime: String                      # ISO timestamp of the scan
  trackingLocation: JSON                # { city, state, zip }
}

Order Status Values

PENDING · CONFIRMED · COMPLETED · BUSTED · IN_DISPUTE · CANCELLED

Transfer Status Values

PENDING · REVIEW · IN_PROGRESS · PENDING_LABEL_GENERATION · AWAITING_SHIPMENT · SHIPPED · AWAITING_RECIPIENT_CONFIRMATION · DELIVERED · COMPLETED · FAILED · CANCELLED · REVERSED · REJECTED · NOT_RECEIVED · MISSED_DEADLINE

Pagination & History

pagination {
  totalCount    # total matching records
  limit         # records per page
  offset        # records skipped
  hasNextPage   # more results available
}

There is no age cutoff — the full order history is returned, newest-first. Page through with pagination: { limit, offset } (loop while hasNextPage is true) or window with createdAfter / createdBefore. For large backfills prefer date windows over deep offsets, since high offset values get progressively slower.

Error Handling

{
  "orders": [],
  "pagination": { "totalCount": 0 },
  "error": { "message": "Error retrieving TPX orders", "code": "TPX_ORDERS_RETRIEVAL_ERROR" }
}

Basic Query​

Filtering​

Shipment Tracking​

Notes​

Input Parameters​

Find a single order​

Filter a list​

Response Fields​

Order​

Asset Payload​

Transfer & ShippingLabel​

Order Status Values​

Transfer Status Values​

Pagination & History​

Error Handling​