> This page is for Developer.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.bigcommerce.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.bigcommerce.com/_mcp/server.

# GraphQL Storefront API: Orders

## Overview

The GraphQL Storefront `orders` object schema can power requests to your [headless](/developer/docs/storefront/headless) storefront or [Stencil](/developer/docs/storefront/stencil/getting-started) 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](/developer/docs/storefront/guides/graphql-storefront-api).

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](/developer/api-reference/rest/storefront/overview).

### 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

> **Note**
>
> **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](/developer/docs/storefront/guides/graphql-storefront-api#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](/developer/docs/storefront/guides/graphql-storefront-api/authentication).

## Example queries

> **Note**
>
> Before running the example queries, you will need to [sign in as a customer](/developer/docs/storefront/guides/graphql-storefront-api/authentication) 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.

#### Request

**`Example query: Get all orders and details`**

```graphql title="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
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get all orders and details`**

```graphql title="Example response: Get all orders and details"
{
  "data": {
    "customer": {
      "orders": {
        "edges": [
          {
            "node": {
              "consignments": {
                "shipping": {
                  "edges":  [
                    {
                    "node": {
                      "lineItems":  {
                        "edges":  [
                            {
                            "node": {
                              "brand": "default",
                              "entityId": "1",
                              "name": "[Sample] Smith Journal 13",
                              "variantEntityId": 43,
                              "productOptions": [
                                {
                                  "name": "Color",
                                  "value": "Yellow",
                                  "productAttributeEntityId": 118,
                                  "productAttributeValueEntityId": 219
                                }
                              ],
                              "quantity": "3"
                            }
                          }
                        ]
                      }
                    }
                    }
                  ]
                }
              },
            "subTotal": {
              "currencyCode": "USD",
              "value": 25.0
              }
            } 
          }
        ]
      }
    }
  } 
}
```

### 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.

#### Request

**`Example query: Get order details`**

```graphql title="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
      }
    }
  }
}
```

#### Response

**`Example response: Get order details`**

```graphQL title="Example response: Get order details" showLineNumbers={false}
{
  "data": {
    "site": {
      "order": {
        "billingAddress": {
          "address1": "1800 Amphibious Blvd.",
          "city": "Mountain View",
          "company": "ExampleOrganization",
          "country": "United States",
          "countryCode": "US",
          "email": "jane.doe@example.com",
          "firstName": "Jane",
          "lastName": "Doe",
          "phone": "(800) 555-0100",
          "postalCode": "94045",
          "stateOrProvince": "California"
        },
        "consignments": {
          "shipping": {
            "edges": [
              {
              "cursor": "ABcYXgjb25uZWN0aW9uOjA=",
              "node": {
                "lineItems": {
                  "edges": [
                    {
                      "node": {
                        "brand": "default",
                        "entityId": 1,
                        "name": "[Sample] Smith Journal 13",
                        "variantEntityId": 43,
                        "subTotalListPrice": {
                            "currencyCode": "USD",
                            "value": 25.0
                        },
                        "downloadPageUrl": null
                      }
                    }
                  ]
                },
                "shipments": {
                  "edges": []
                },
                "shippingAddress": {
                  "address1": "Avenida da Pastelaria, 1903",
                  "city": "Lisbon",
                  "firstName": "Kai",
                  "lastName": "N.",
                  "postalCode": "1229-076",
                  "stateOrProvince": "Rio del chocolate"
                },
                "shippingCost": {
                  "currencyCode": "USD",
                    "value": 0.0
                }
              }
            }
          ]
        }
      },
      "subTotal": {
          "currencyCode": "USD",
          "value": 25.0
      },
      "taxTotal": {
          "currencyCode": "USD",
          "value": 0.0
      },
      "totalIncTax": {
          "currencyCode": "USD",
          "value": 0.0
      },
      "updatedAt": {
          "utc": "2024-04-02T15:04:08Z"
      },
      "poNumber": "PO-1024",
      "reference": "REF-4471",
      "company": {
          "entityId": 1,
          "name": "ExampleOrganization"
      },
      "placedBy": {
          "entityId": 123,
          "firstName": "Jane",
          "lastName": "Doe",
          "email": "jane.doe@example.com"
      },
      "invoice": {
          "id": "5512"
      },
      "history": [
          {
              "id": "8801",
              "eventType": "ORDER_CREATED",
              "statusLabel": "Awaiting Fulfillment",
              "source": "B2B",
              "createdAt": "2026-03-14T09:21:44Z"
          }
      ],
      "extraFields": [
          {
              "name": "extra_str_1",
              "value": "Purchasing dept"
          }
      ]
    }
  }
}
}
```

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.

#### Request

**`Example query: Get company orders`**

```graphql title="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
            }
          }
        }
      }
    }
  }
}
```

#### Response

**`Example response: Get company orders`**

```json title="Example response: Get company orders" showLineNumbers={false}
{
  "data": {
    "customer": {
      "activeCompany": {
        "orders": {
          "pageInfo": {
            "hasNextPage": false,
            "hasPreviousPage": false,
            "startCursor": "YXJyYXljb25uZWN0aW9uOjA=",
            "endCursor": "YXJyYXljb25uZWN0aW9uOjA="
          },
          "collectionInfo": {
            "totalItems": 1
          },
          "edges": [
            {
              "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
              "node": {
                "entityId": 106,
                "orderedAt": {
                  "utc": "2026-03-14T09:21:44Z"
                },
                "status": {
                  "label": "Completed",
                  "value": "COMPLETED"
                },
                "totalIncTax": {
                  "currencyCode": "USD",
                  "value": 25.0
                },
                "poNumber": "PO-1024",
                "reference": "REF-4471",
                "placedBy": {
                  "entityId": 123,
                  "firstName": "Jane",
                  "lastName": "Doe"
                },
                "company": {
                  "entityId": 1,
                  "name": "ExampleOrganization"
                }
              }
            }
          ]
        }
      }
    }
  }
}
```

### 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.

#### Request

**`Example query: Get order metafield`**

```graphql title="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
                 }
             }
         }
         
     }
 }
 
}
```

#### Response

**`Example response: Get order metafield`**

```graphQL title="Example response: Get order metafield"
{
"data": {
 "site": {
   "order": {
     "entityId": 102,
     "metafields": {
       "edges": [
         {
           "node": {
             "key": "Order metafield for order 102",
             "value": "Order metafield for order 102"
           }
         }
       ]
     },
     "cartMetafields": {
       "edges": [
         {
           "node": {
             "key": "Cart metafield for order 102",
             "value": "Cart metafield for order 102"
           }
         }
       ]
     }
   }
 }
}
}
```

### 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.

#### Request

**`Example query: Get metafields`**

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

#### Response

**`Example response: Get metafields`**

```graphql title="Example response: Get metafields"
 {
  "data": {
      "customer": {
          "orders": {
              "edges": [
                  {
                      "node": {
                          "entityId": 1234000006,
                          "metafields": {
                              "edges": []
                          }
                      }
                  },
                  {
                      "node": {
                          "entityId": 1234000005,
                          "metafields": {
                              "edges": []
                          }
                      }
                  },
                  {
                      "node": {
                          "entityId": 1234000004,
                          "metafields": {
                              "edges": []
                          }
                      }
                  }
              ]
          }
      }
  }
} 
```

Join our [Developer community](https://support.bigcommerce.com/s/community) to share your feedback with us in the BigCommerceDevs Slack.

## Resources

### Documentation

* [GraphQL storefront API overview](/developer/docs/storefront/guides/graphql-storefront-api)
* [Guide to API Accounts: Store-level API accounts](/developer/docs/overview/api-fundamentals/api-accounts#store-level-api-accounts)
* [Guide to API accounts: OAuth token creation scopes](/developer/docs/overview/api-fundamentals/api-accounts#token-creation-scopes)
* [Authentication and example requests: BigCommerce-generated JWTs](/developer/docs/overview/api-fundamentals/api-accounts#bigcommerce-generated-jwts)

### API reference

#### Storefront tokens

* [Create a storefront token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/create-token)
* [Create a customer impersonation token](/developer/api-reference/rest/admin/authentication-apis/storefront-api-tokens/customer-impersonation-token/create-token-with-customer-impersonation)

#### Storefront API: orders

* [Storefront Orders](/developer/api-reference/rest/storefront/orders)

#### REST Management API: orders

* [Orders V2](/developer/api-reference/rest/admin/management/orders)
* [Orders V3](/developer/api-reference/rest/admin/management/order-operations)

### Community

* [Developer community](https://support.bigcommerce.com/s/community)