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.
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.
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.
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.
{
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
- GraphQL storefront API overview
- Guide to API Accounts: Store-level API accounts
- Guide to API accounts: OAuth token creation scopes
- Authentication and example requests: BigCommerce-generated JWTs