Orders

Introduction

Working with orders in the B2B GraphQL API is fairly straightforward. The storefront experience of placing an order, for both B2B and B2C customers, relies on the BigCommerce checkout or use of the standard BigCommerce APIs. Therefore, the GraphQL Storefront API only handles the use case of fetching the details of a company’s existing orders and ordered products.

Fetching Company Orders

The current company’s orders can be fetched with the allOrders query.

Example query and response:

query GetOrders {
    allOrders {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                bcOrderId
                createdAt
                userId
                bcCustomerId
                companyId {
                    id
                    companyName
                }
                totalIncTax
                currencyCode
                items
                poNumber
                status
                shippingAddress
                shipments
                products
                customer
                companyName
                firstName
                lastName
            }
        }
    }
}

• allOrders supports typical pagination arguments.
• Other available filtering arguments include beginDateAt and endDateAt, which accept date string values like “2025-01-01”.
• The order fields include both B2B entity IDs (idand userId) and core BigCommerce IDs (bcOrderId and bcCustomerId) of both the order records and associated customer/user records.
• Note that despite the field name, companyId contains a company object on which specific fields must be queried.
• items contains a count of the total items in the order. While this query doesn’t expose a field that returns an array of the order items, note that products contains an encoded JSON string of the full BigCommerce order product details, which can be decoded in your application.
• Similar to products, shippingAddress, shipments, and customer contain JSON strings with full details of the shipping address, shipments (if any), and the associated customer record.

Fetching a Single Order

A single order’s details can be fetched with the order query using the order’s BigCommerce ID.

Example query, variables, and response:

query GetOrder(
    $id: Int!
) {
    order(
        id: $id
    ) {
        id
        firstName
        lastName
        status
        customerId
        dateCreated
        subtotalExTax
        subtotalIncTax
        subtotalTax
        baseShippingCost
        shippingCostExTax
        shippingCostIncTax
        totalTax
        discountAmount
        totalExTax
        totalIncTax
        itemsTotal
        itemsShipped
        paymentMethod
        poNumber
        products
        billingAddress
        shippingAddress
        shipments
        invoiceId
        orderHistoryEvent {
            id
            eventType
            status
        }
    }
}

Note that order returns a different GraphQL type than the nodes returned by allOrders, and in this case more granular details about the order can be queried than with the “list” query.

Many fields have been truncated from the above example, but note the following details:

• If the order originated with a quote, whether the negotiated discount will be represented as an order discount or reflected in the item prices/subtotal depends on the type of discount that was applied.
• The product price tax_field contains the amount of tax based on the item’s non-discounted price, while total tax_contains the final tax amount.
• products, billingAddress, shippingAddress, and shipments return complex objects, but their GraphQL types do not allow more granular querying of their sub-fields.
• orderHistoryEvent contains a history of the order’s status changes.

Inspecting Ordered Products

With the orderedProducts query, historical information about a company’s previously ordered products can be queried, including the number of times ordered and first/last ordered dates.

Example query and response:

query GetOrderedProducts {
    orderedProducts {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        totalCount
        edges {
            node {
                id
                productId
                productName
                sku
                variantSku
                variantId
                optionList
                optionSelections
                orderedTimes
                firstOrderedAt
                lastOrderedAt
                imageUrl
                productUrl
            }
        }
    }
}

• orderedProducts supports standard pagination arguments.
• The query can also be filtered by the number of times a product has been ordered, using the minOrderedTimes and maxOrderedTimes arguments.
• The query can also be filtered by the order date range, using the beginDateAt and endDateAt arguments. These arguments accept a date string like “2025-01-01”.