> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmhouse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Query order history across a customer's subscriptions

> Fetch a customer's orders in one paginated GraphQL connection, filtered by email and order statuses.

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](https://docs.firmhouse.com/integrations/api-access-tokens.md) 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.

```graphql theme={null}
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:

```json theme={null}
{
  "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](https://docs.firmhouse.com/developers/guides/run-graphql-bulk-operation-queries.md). Bulk operations run asynchronously; use normal paginated queries for a customer opening their history page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.