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.

Request

Response

Example query: Get all orders and details

1 query 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.

Request

Response

Example query: Get order details

1 query 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.

Request

Response

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.

Request

Response

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

Storefront Orders

REST Management API: orders

Community

Developer community

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

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.

Request

Response

Example query: Get all orders and details

1 query 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.

Request

Response

Example query: Get order details

1 query 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.

Request

Response

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.

Request

Response

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.

1	query 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	}

1	query 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	}

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	}

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	}

Overview

Fetch orders detail

Fetch order details

Authorization

Example queries

Get all orders and details

Filter by order status

Request

Response

Get order details

Request

Response

Get an order metafield

Request

Response

Get metafields for a customer

Request

Response

Resources

Documentation

API reference

Storefront tokens

Storefront API: orders

REST Management API: orders

Community

Overview

Fetch orders detail

Fetch order details

Authorization

Example queries

Get all orders and details

Filter by order status

Request

Response

Get order details

Request

Response

Get an order metafield

Request

Response

Get metafields for a customer

Request

Response

Resources

Documentation

API reference

Storefront tokens

Storefront API: orders

REST Management API: orders

Community

Fetch `orders` detail

Fetch `order` details

Fetch `orders` detail

Fetch `order` details