Skip to navigation
DocsStorefrontGuidesGraphQL Storefront

GraphQL Storefront API: Orders

Overview

The GraphQL Storefront orders object schema can power requests to your headless storefront or Stencil theme supplying you with instant access to your Orders storefront data. To learn more about how the BigCommerce Storefront graph works, see GraphQL Storefront API overview.

In this document, you can learn how to use queries and operation types to fetch order data using the BigCommerce Storefront graph. Create arguments for fields like filtering orders by entity_Id. You’re encouraged to read on and put these example queries into practice by using the BigCommerce GraphQL Playground.

Fetch orders detail

Use the orders object type to fetch data in order to display the orders and details on the storefront graph.

Use the GetAllOrders query field to fetch all orders for a specific customer. You can get a customer’s order history, and get details like:

  • Billing address, including the customer’s details
  • Order status
  • Consignment orders information
  • Specific discounts, and coupons (when applied)
  • Pricing

The following features are coming soon

  • Payment/Payments information
  • Order specific messages

Fetch order details

Use the order object type to get detailed information on the storefront graph.

Use the GetOrderDetails field query to fetch order details like:

  • Specific customer orders
  • Specific order data filtered by date, or status

Note: Don’t forget to include cursor pagination to refine the fetched information.

Authorization

Use your bearer token to perform the example queries on your storefront instance in the next section.

To learn more about authenticating requests to the GraphQL Storefront API, see Authenticating requests to the GraphQL Storefront API.

Example queries

Before running the example queries, you will need to sign in as a customer for the queries to work.

Get all orders and details

Filter by order status

In this example, the query is set up to return a filtered list of all orders with a COMPLETED status.

Example query: Get all orders and details
query GetAllOrders {
  customer {
    orders(filters: {status: COMPLETED}) {
      edges {
        node {
          consignments {
            shipping {
              edges {
                node {
                  lineItems {
                    edges {
                      node {
                        brand
                        entityId
                        name
                        variantEntityId
                        productOptions {
                          name
                          value
                          productAttributeEntityId
                          productAttributeValueEntityId
                        }
                        quantity
                      }
                    }
                  }
                }
              }
            }
          }
          subTotal {
            currencyCode
            value
          }
        }
      }
    }
  }
}

Get order details

In this example, the query gets details for order #106. Use entityId to query by order. Authorized B2B company users can retrieve order details for orders placed by other company users on the current storefront channel. The B2B order fields require a B2B storefront token.

Example query: Get order details
query GetOrderDetails {
  site {
    order(filter: { entityId: 106 }) {
      billingAddress {
        address1
        city
        company
        country
        countryCode
        email
        firstName
        lastName
        phone
        postalCode
        stateOrProvince
      }
      consignments {
        shipping {
          edges {
              cursor
              node {
              lineItems {
                edges {
                  node {
                    brand
                    entityId
                    name
                    variantEntityId
                    subTotalListPrice {
                      currencyCode
                      value
                    }
                    downloadPageUrl
                  }
                }
              }
              shipments {
                edges {
                  node {
                    shippingProviderName
                    tracking {
                      ... on OrderShipmentUrlOnlyTracking {
                          __typename
                      }
                    }
                  }
                }
              }
              shippingAddress {
                address1
                city
                firstName
                lastName
                postalCode
                stateOrProvince
              }
              shippingCost {
                currencyCode
                  value
              }
            }
          }
        }
      }
      subTotal {
        currencyCode
        value
      }
      taxTotal {
        currencyCode
        value
      }
      totalIncTax {
        currencyCode
        value
      }
      updatedAt {
        utc
      }
      poNumber
      reference
      company {
        entityId
        name
      }
      placedBy {
        entityId
        firstName
        lastName
        email
      }
      invoice {
        id
      }
      history {
        id
        eventType
        statusLabel
        source
        createdAt
      }
      extraFields {
        name
        value
      }
    }
  }
}

Physical line items return downloadPageUrl only when the item bundles a downloadable digital product and the order’s digital products are available for download. Otherwise, as in this example, the field is null.

Get company orders

In this example, the query returns a page of orders placed on the current storefront channel by any user in the customer’s active company. The sortBy argument uses the CompanyOrdersSortInput enum to sort the orders from newest to oldest.

Example query: Get company orders
query GetCompanyOrders {
  customer {
    activeCompany {
      orders(
        first: 10
        filters: {
          status: ["Completed"]
          customerId: [123]
          companyIds: ["1"]
          dateRange: { from: "2026-01-01T00:00:00Z", to: "2026-06-30T23:59:59Z" }
        }
        sortBy: CREATED_AT_NEWEST
      ) {
        pageInfo {
          hasNextPage
          hasPreviousPage
          startCursor
          endCursor
        }
        collectionInfo {
          totalItems
        }
        edges {
          cursor
          node {
            entityId
            orderedAt {
              utc
            }
            status {
              label
              value
            }
            totalIncTax {
              currencyCode
              value
            }
            poNumber
            reference
            placedBy {
              entityId
              firstName
              lastName
            }
            company {
              entityId
              name
            }
          }
        }
      }
    }
  }
}

Get an order metafield

In this example, the query is set up to get a metafield for order #102. Use entityId to query by order.

Example query: Get order metafield
 query Order($namespace: String!) {
 site {
     order(filter: {entityId: 102}) {
         id
         entityId
         billingAddress {
             firstName
         }
         metafields(namespace: $namespace) {
             edges {
                 node {
                     key
                     value
                 }
             }
         }
         cartMetafields(namespace: $namespace) {
             edges {
                  node {
                     key
                     value
                 }
             }
         }
         
     }
 }
 
}

Get metafields for a customer

In this example, the query is set up to get metafields for a customer. Ensure the customer is logged-in.

Example query: Get metafields
{
  customer {
    orders {
      edges {
        node {
          entityId
          metafields(namespace: "my-namespace") {
            edges {
              node {
                value
              }
            }
          }
        }
      }
    }
  }
}

Join our Developer community to share your feedback with us in the BigCommerceDevs Slack.

Resources

Documentation

API reference

Storefront tokens

Storefront API: orders

REST Management API: orders

Community