Query order history across a customer's subscriptions

Use the top-level orders connection to build a customer’s order history across their subscriptions. Filter by email and request the fields needed for the visible page in the same query. This avoids listing each subscription, paging through each subscription’s orders, and then fetching the selected orders separately.

Query a page of history

Authenticate on your server with a project API access token with read access. Derive the customer’s email from their authenticated storefront session. Keep the project token on your server and verify customer identity before returning their orders.

query CustomerOrderHistory(
  $email: String!
  $after: String
  $createdSince: ISO8601DateTime
) {
  orders(
    email: $email
    statuses: [CONFIRMED, FULFILLED]
    createdSince: $createdSince
    first: 9
    after: $after
    orderBy: CREATED_AT
  ) {
    nodes {
      id
      status
      amountCents
      currency
      createdAt
      shipmentDate
      trackingCode
      paid
      metadata
      orderLines { quantity }
      subscription { id token }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Example variables:

{
  "email": "customer@example.com",
  "after": null,
  "createdSince": "2026-01-01T00:00:00Z"
}

The result combines matching orders across subscriptions in newest-first order. Orders created at the same time are sorted by descending ID to keep pagination consistent. When hasNextPage is true, pass endCursor as after with the same filters to retrieve the next page. Fetch a page when the customer opens it; a history page does not require downloading their entire order history first.

Filter behavior

email matches the subscription’s current email address exactly, ignoring letter case, within the authenticated project. It can match multiple subscriptions, including cancelled subscriptions with historical orders. Subscription-token requests use that subscription’s project and remain limited to orders the caller can read.
Omitting email leaves the existing authorized order scope unchanged. A project token can read other customers’ orders, so always supply the authenticated customer’s email for a customer-facing history page.
statuses includes orders matching any listed status. An empty list returns no orders; omitting the list leaves statuses unrestricted.
The existing status argument still works. If both status and statuses are supplied, orders must satisfy both filters.
createdSince filters the order creation time, independently of when its subscription was updated. Omit it to include older orders.

These filters also work on a subscription’s ordersV2 connection, where results remain limited to that subscription.

Keep requests bounded

Request the fields needed for one page. The example fetches nine order cards in a single GraphQL request, regardless of the number of matching subscriptions. Normal pagination and query complexity limits still apply. For background exports and synchronization, use GraphQL bulk operations. Bulk operations run asynchronously; use normal paginated queries for a customer opening their history page.

​Query a page of history

​Filter behavior

​Keep requests bounded

Query a page of history

Filter behavior

Keep requests bounded