List Orders

Get a paginated list of orders placed on your store. Filter by status or date range.

GET/orders

List Orders

Retrieve a paginated list of orders with optional filtering. Test API keys only see test orders.

On larger screens, use the API Playground panel on the right to try this endpoint.

Name	Type	Required	Description
`page`	number	Optional	Page number (1-indexed)Default: `1`
`limit`	number	Optional	Items per page (max 100)Default: `50`
`status`	stringawaiting_shipment \| shipped \| delivered \| completed \| disputed \| cancelled \| refunded	Optional	Filter by order status
`since`	string	Optional	Filter orders created after this ISO date (ISO 8601)

bash

curl "https://api.ctcgx.com/api/v1/orders" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

Returns a paginated list of orders with item details and buyer information.

json

{
  "orders": [
    {
      "id": "clxxx...",
      "orderNumber": 12345,
      "status": "awaiting_shipment",
      "subtotal": 1599,
      "shippingCost": 500,
      "total": 2099,
      "shippingMethod": "Standard Shipping",
      "shippingAddress": {
        "street": "123 Main St",
        "city": "Toronto",
        "province": "ON",
        "postalCode": "M5V 1A1",
        "country": "CA"
      },
      "trackingNumber": null,
      "carrier": null,
      "createdAt": "2024-01-15T10:00:00.000Z",
      "shippedAt": null,
      "deliveredAt": null,
      "items": [
        {
          "listingId": "clyyy...",
          "productId": "clzzz...",
          "productName": "Black Lotus",
          "quantity": 1,
          "priceAtPurchase": 1599,
          "condition": "NM",
          "finish": "nonfoil"
        }
      ],
      "buyer": {
        "username": "cardcollector"
      }
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

Common Use Cases

# Get orders ready to ship
GET /orders?status=awaiting_shipment

# Get shipped orders
GET /orders?status=shipped

# Get orders from the last 24 hours
GET /orders?since=2024-01-14T10:00:00Z

# Get all orders with pagination
GET /orders?page=1&limit=50

Order Status Lifecycle

Orders follow this lifecycle:

awaiting_shipment → shipped → delivered → completed
                                       ↘ disputed

awaiting_shipment - Order paid, waiting for seller to ship
shipped - Seller has shipped the order
delivered - Package delivered, awaiting buyer confirmation
completed - Buyer confirmed receipt
disputed - Buyer opened a dispute
cancelled - Order was cancelled
refunded - Order was refunded