> 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. # Orders Plan: B2B Developer Lesson 13 of 18 ยท 30 min ## 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. > **Info** > > The *order-related queries* are available to any of the built-in user roles, or a custom role with the "Orders - View" permission. ## Fetching Company Orders The current company's orders can be fetched with the `allOrders` query. ### Example query and response: #### Query ```graphql showLineNumbers={false} 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 } } } } ``` #### Response ```json showLineNumbers={false} { "data": { "allOrders": { "pageInfo": { "hasNextPage": true, "hasPreviousPage": false, "startCursor": "YXJy...", "endCursor": "YXJy..." }, "totalCount": 20, "edges": [ { "node": { "id": "44455566", "bcOrderId": 120, "createdAt": 1724273249, "userId": 99988877, "bcCustomerId": 27, "companyId": { "id": "1112233", "companyName": "John's Widgets" }, "totalIncTax": 325.52, "currencyCode": "USD", "items": 2, "poNumber": "12345", "status": "Shipped", "shippingAddress": "[{\"id\": 11, \"zip\": \"78726\", \"city\": \"Austin\",...}]", "shipments":"[{\"id\": 2, \"items\": [{\"quantity\": 1, \"product_id\": 20,...}],...}]", "products": "[{\"id\": 20, \"sku\": \"AWE-T\", ...}]", "customer": "{\"id\": 27, \"email\": \"johndoe@example.com\",...}", "companyName": "John's Widgets", "firstName": "John", "lastName": "Doe" } }, ... ] } } } ``` * `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 (`id`and `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 ```graphql showLineNumbers={false} 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 } } } ``` #### Variables ```json showLineNumbers={false} { "id": 120 } ``` #### Response ```json showLineNumbers={false} { "data": { "order": { "id": "120", "firstName": "John", "lastName": "Doe", "status": "Shipped", "customerId": 27, "dateCreated": "Wed, 21 Aug 2025 20:47:25 +0000", "subtotalExTax": "341.0000", "subtotalIncTax": "363.1800", "subtotalTax": "22.1800", "baseShippingCost": "9.0000", "shippingCostExTax": "9.0000", "shippingCostIncTax": "10.1700", "totalTax": "25.5200", "discountAmount": "50.0000", "totalExTax": "300.0000", "totalIncTax": "325.5200", "itemsTotal": 2, "itemsShipped": 2, "paymentMethod": "Purchase Order", "poNumber": "12345", "products": [ { "id": 20, "sku": "AWE-T", ... "quantity": 1, "price_tax": "6.2350", "return_id": 0, "total_tax": "3.7200", "base_price": "89.0000", "base_total": "89.0000", ... "product_id": 20, ... "price_ex_tax": "89.0000", "total_ex_tax": "89.0000", ... "price_inc_tax": "95.2350", "refund_amount": "0.0000", "total_inc_tax": "95.2350", ... "quantity_shipped": 1, ... "applied_discounts": [ { "id": "manual-discount", "code": null, "name": "Manual Discount", "amount": "35.9000", "target": "order" } ], ... "discounted_total_inc_tax": "56.8200", ... }, ... ], "billingAddress": { "zip": "78726", "city": "Austin", ... }, "shippingAddress": [ { "id": 11, "zip": "78726", "city": "Austin", ... } ], "shipments": [ { "id": 2, "items": [ { "quantity": 1, "product_id": 20, "order_product_id": 18 }, ... ], ... "shipping_method": "Flat Rate", "tracking_number": "123456789", ... } ], "invoiceId": 7778899, "orderHistoryEvent": [ { "id": 11111111, "eventType": 2, "status": "Shipped" }, { "id": 22222222, "eventType": 2, "status": "Awaiting Payment" } ] } } } ``` 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 ```graphql showLineNumbers={false} query GetOrderedProducts { orderedProducts { pageInfo { hasNextPage hasPreviousPage startCursor endCursor } totalCount edges { node { id productId productName sku variantSku variantId optionList optionSelections orderedTimes firstOrderedAt lastOrderedAt imageUrl productUrl } } } } ``` #### Response ```json showLineNumbers={false} { "data": { "orderedProducts": { "pageInfo": { "hasNextPage": true, "hasPreviousPage": false, "startCursor": "YXJy...", "endCursor": "YXJy..." }, "totalCount": 50, "edges": [ { "node": { "id": "T3Jk...", "productId": "20", "productName": "Awesome T-Shirt", "sku": "AWE-T", "variantSku": "AWE-T-SM-R", "variantId": "17", "optionList": [ { "id": 8, "option_id": 3, "order_product_id": 36, "product_option_id": 111, ... }, ... ], "optionSelections": [ { "option_id": 100, "value_id": 1000 }, { "option_id": 101, "value_id": 2000 } ], "orderedTimes": "3", "firstOrderedAt": 1724274130, "lastOrderedAt": 1759804358, "imageUrl": "https://cdn11.bigcommerce.com/...", "productUrl": "/awesome-tshirt/" } }, ... ] } } } ``` * `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".