StorefrontGuidesGraphQL Storefront

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 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
1query GetAllOrders {
2  customer {
3    orders(filters: {status: COMPLETED}) {
4      edges {
5        node {
6          consignments {
7            shipping {
8              edges {
9                node {
10                  lineItems {
11                    edges {
12                      node {
13                        brand
14                        entityId
15                        name
16                        productOptions {
17                          name
18                          value
19                        }
20                        quantity
21                      }
22                    }
23                  }
24                }
25              }
26            }
27          }
28          subTotal {
29            currencyCode
30            value
31          }
32        }
33      }
34    }
35  }
36}

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
1query GetOrderDetails {
2  site {
3    order(filter: { entityId: 106 }) {
4      billingAddress {
5        address1
6        city
7        company
8        country
9        countryCode
10        email
11        firstName
12        lastName
13        phone
14        postalCode
15        stateOrProvince
16      }
17      consignments {
18        shipping {
19          edges {
20              cursor
21              node {
22              lineItems {
23                edges {
24                  node {
25                    brand
26                    entityId
27                    name
28                    subTotalListPrice {
29                      currencyCode
30                      value
31                    }
32                  }
33                }
34              }
35              shipments {
36                edges {
37                  node {
38                    shippingProviderName
39                    tracking {
40                      ... on OrderShipmentUrlOnlyTracking {
41                          __typename
42                      }
43                    }
44                  }
45                }
46              }
47              shippingAddress {
48                address1
49                city
50                firstName
51                lastName
52                postalCode
53                stateOrProvince
54              }
55              shippingCost {
56                currencyCode
57                  value
58              }
59            }
60          }
61        }
62      }
63      subTotal {
64        currencyCode
65        value
66      }
67      taxTotal {
68        currencyCode
69        value
70      }
71      totalIncTax {
72        currencyCode
73        value
74      }
75      updatedAt {
76        utc
77      }
78    }
79  }
80}

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
1 query Order($namespace: String!) {
2 site {
3     order(filter: {entityId: 102}) {
4         id
5         entityId
6         billingAddress {
7             firstName
8         }
9         metafields(namespace: $namespace) {
10             edges {
11                 node {
12                     key
13                     value
14                 }
15             }
16         }
17         cartMetafields(namespace: $namespace) {
18             edges {
19                  node {
20                     key
21                     value
22                 }
23             }
24         }
25         
26     }
27 }
28 
29}

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
1{
2  customer {
3    orders {
4      edges {
5        node {
6          entityId
7          metafields(namespace: "my-namespace") {
8            edges {
9              node {
10                value
11              }
12            }
13          }
14        }
15      }
16    }
17  }
18}

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

Storefront API: orders

REST Management API: orders

Community