Query Orders

Retrieve your TPX purchase orders with flexible filtering options.

Endpoint

query getMyTpxOrders($input: GetMyTpxOrdersInput!)

Use Cases

• Track order status and fulfillment progress
• Reconcile purchase amounts with accounting systems
• Debug specific auction outcomes
• Monitor order volume and trends

Example Queries

Query by ICO ID

query {
  getMyTpxOrders(input: {
    instantCashOfferId: "8801e2de-d04d-4198-ad9a-30f18364b1c3"
    pagination: { limit: 20, offset: 0 }
  }) {
    orders {
      id
      status
      totalAmountCents
      quantity
      createdAt
    }
    pagination {
      totalCount
      hasNextPage
    }
  }
}

Query by External Reference ID

query {
  getMyTpxOrders(input: {
    externalReferenceId: "my-tracking-id-123"
    pagination: { limit: 10, offset: 0 }
  }) {
    orders {
      id
      status
      buyerAccountId
      totalAmountCents
      transferDeadline
      missedDeadline
    }
    pagination {
      totalCount
    }
  }
}

Filter by Status and Date Range

query {
  getMyTpxOrders(input: {
    statuses: ["COMPLETED"]
    createdAfter: "2025-11-01T00:00:00Z"
    createdBefore: "2025-11-30T23:59:59Z"
    pagination: { limit: 50, offset: 0 }
  }) {
    orders {
      id
      status
      totalAmountCents
      createdAt
    }
    pagination {
      totalCount
    }
  }
}

Filter by Transfer Status

query {
  getMyTpxOrders(input: {
    transferStatuses: ["AWAITING_RECIPIENT_CONFIRMATION"]
    pagination: { limit: 20, offset: 0 }
  }) {
    orders {
      id
      status
      totalAmountCents
      createdAt
    }
    pagination {
      totalCount
      hasNextPage
    }
  }
}

Filter by Tracking Code

query {
  getMyTpxOrders(input: {
    trackingCode: "1Z999AA10123456784"
    pagination: { limit: 20, offset: 0 }
  }) {
    orders {
      id
      status
      totalAmountCents
      createdAt
    }
    pagination {
      totalCount
    }
  }
}

Filter by Recipient Address

query {
  getMyTpxOrders(input: {
    recipientAddressId: "f7a8b9c0-d1e2-3456-7890-abcdef123456"
    pagination: { limit: 20, offset: 0 }
  }) {
    orders {
      id
      status
      totalAmountCents
      createdAt
    }
    pagination {
      totalCount
    }
  }
}

Filter by Asset Type and Quantity

query {
  getMyTpxOrders(input: {
    assetTypeIds: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
    minQuantity: 1
    maxQuantity: 10
    pagination: { limit: 20, offset: 0 }
  }) {
    orders {
      id
      status
      quantity
      totalAmountCents
      createdAt
    }
    pagination {
      totalCount
    }
  }
}

Input Parameters

Reference ID filters

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

Terminal UI filters

Field	Type	Description
assetConfigId	ID	Filter by asset configuration ID
strategyId	ID	Filter by strategy ID
subjectId	ID	Filter by subject ID
venueId	ID	Filter by venue ID

Date range filters

Field	Type	Description
createdAfter	DateTime	Filter by creation date (greater than or equal)
createdBefore	DateTime	Filter by creation date (less than or equal)
updatedAfter	DateTime	Filter by update date (greater than or equal)
updatedBefore	DateTime	Filter by update date (less than or equal)

Status filters

Field	Type	Description
statuses	[String!]	Filter by order status (PENDING, CONFIRMED, COMPLETED, BUSTED, IN_DISPUTE, CANCELLED)
transferStatuses	[String!]	Filter by transfer status (see Transfer Status Values below)

Shipment filter

Field	Type	Description
trackingCode	String	Filter by shipment tracking code

Recipient address filter

Field	Type	Description
recipientAddressId	ID	Filter by saved recipient address ID

Asset filters

Field	Type	Description
assetConfigName	String	Filter by asset configuration name
assetTypeIds	[ID!]	Filter by one or more asset type IDs

Quantity filters

Field	Type	Description
minQuantity	Int	Minimum order quantity (inclusive)
maxQuantity	Int	Maximum order quantity (inclusive)

Pagination

Field	Type	Description
pagination	SimplePaginationInput	Limit and offset

Response Fields

Order Object

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
}

Order Status Values

• PENDING - Order created, payment processing
• CONFIRMED - Payment confirmed, awaiting transfer
• COMPLETED - Transfer completed successfully
• BUSTED - Transfer missed deadline
• IN_DISPUTE - Order under dispute
• CANCELLED - Order cancelled

Transfer Status Values

• PENDING - Transfer created, collecting required info
• REVIEW - Transfer under manual review/approval
• IN_PROGRESS - General processing status
• PENDING_LABEL_GENERATION - Address collected, generating shipping labels
• AWAITING_SHIPMENT - Labels generated, ready for carrier pickup
• SHIPPED - Package picked up by carrier (in-transit)
• AWAITING_RECIPIENT_CONFIRMATION - Delivered, awaiting partner confirmation
• DELIVERED - Successfully delivered to recipient
• COMPLETED - Transfer fully processed and finalized
• FAILED - Transfer failed due to system error
• CANCELLED - Transfer cancelled
• REVERSED - Transfer reversed/refunded after completion
• REJECTED - Transfer rejected during review
• NOT_RECEIVED - Partner confirmed non-receipt
• MISSED_DEADLINE - Transfer expired due to missed deadline

Pagination

pagination {
  totalCount    # Total matching records
  limit         # Records per page
  offset        # Records skipped
  hasNextPage   # More results available
}

Best Practices

1. Use specific filters - Combine reference IDs with date ranges for faster queries
2. Reasonable page sizes - Use limit: 20-50 for best performance
3. Cache results - Store frequently accessed data locally
4. Monitor totalCount - Check if you're approaching pagination limits

Error Handling

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

Common errors:

• Invalid status values
• Database connection timeout