Developers

API Explorer

Reference and live testing for the public REST API.

Sign in to manage keys
GET

List orders

/api/v1/orders?page=1&limit=20&timeZone=Asia%2FBangkok&sortBy=orderDate&sortOrder=desc

Returns a paginated list of orders for shops accessible to your API key. Combine filters (shops, dates, search, fulfillment, tracking, sort). Requires the orders:read scope.

Required scope:
orders:read

Parameters

NameInTypeRequiredDefaultDescription
page
query
number
No1Page number (1-based). Default: 1.
limit
query
number
No20Items per page (max 100). Default: 20.
shopEtsyId
query
string[]
No—Filter one or more shops by Etsy shop ID (shopEtsyId from the response). Add multiple IDs below or use comma-separated values. Omit for all accessible shops.
search
query
string
No—Search order ID, recipient name, or address fields.
startDate
query
date
No—Inclusive start date (YYYY-MM-DD) for orderDate filter.
endDate
query
date
No—Inclusive end date (YYYY-MM-DD) for orderDate filter.
timeZone
query
string
NoAsia/BangkokIANA time zone for date filters. Default: Asia/Bangkok.
fulfillmentStatus
query
string
No—Filter by fulfillment: fulfilled, synced_to_provider, manual, pending, or failed.
tracking
query
string
No—Filter by tracking: has (with tracking number) or none.
sortBy
query
string
NoorderDateSort field: orderDate, orderId, recipientName, totalCost, or shop. Default: orderDate.
sortOrder
query
string
Nodescasc or desc. Default: desc.

Common errors

  • 401
    MISSING_API_KEYMissing or invalid API key.
  • 401
    INVALID_API_KEYMissing or invalid API key.
  • 400
    INVALID_QUERY_PARAMOne or more query parameters are invalid.
  • 400
    INVALID_DATE_FORMATDate query parameters must use YYYY-MM-DD.
  • 403
    FORBIDDEN_SHOPOne or more Etsy shop IDs are not accessible for this key.
  • 429
    RATE_LIMITEDToo many requests. Retry after the Retry-After header value.

Sample response

{
  "data": [
    {
      "id": "clx000000000000000000000001",
      "shopId": "clx000000000000000000000002",
      "orderId": "1234567890",
      "orderDate": "2026-07-31T10:00:00.000Z",
      "totalCostFormatted": "$24.99",
      "currencyCode": "USD",
      "shop": {
        "id": "clx000000000000000000000002",
        "shopName": "My Etsy Shop",
        "shopEtsyId": "12345"
      },
      "items": []
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}