Docs
Storefront
GraphQL Storefront API
Orders

GraphQL Storefront API: Orders (beta)

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 (opens in a new tab) 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
                        productOptions {
                          name
                          value
                        }
                        quantity
                      }
                    }
                  }
                }
              }
            }
          }
          subTotal {
            currencyCode
            value
          }
        }
      }
    }
  }
}

Get order details

In this example, the query is set up to get details for order #106. Use entityId to query by customer.

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
                    subTotalListPrice {
                      currencyCode
                      value
                    }
                  }
                }
              }
              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
      }
    }
  }
}

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 or on our Discord server.

Resources

Documentation

API reference

Storefront tokens

GraphQL Storefront API: orders

REST Management API: orders

Community

Did you find what you were looking for?
CustomersProduct reviews