> 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 Overview > Retrieve, create, and update orders, transactions, shipments, and refunds using the Orders v2 and v3 REST APIs. This article introduces BigCommerce's [Orders V2](/developer/api-reference/rest/admin/management/orders) and [Orders V3](/developer/api-reference/rest/admin/management/order-operations) REST API resources. [Orders V2](/developer/api-reference/rest/admin/management/orders) exposes endpoints for [creating](/developer/api-reference/rest/admin/management/orders/create-order), [reading](/developer/api-reference/rest/admin/management/orders/get-orders), [updating](/developer/api-reference/rest/admin/management/orders/update-order), and [deleting](/developer/api-reference/rest/admin/management/orders/delete-orders) orders; it also includes endpoints for managing [order shipments](/developer/api-reference/rest/admin/management/orders/order-shipments/delete-order-shipments) and [order shipping addresses](/developer/api-reference/rest/admin/management/orders). [Orders V3](/developer/api-reference/rest/admin/management/order-operations) surfaces [order transactions](/developer/api-reference/rest/admin/management/order-operations/get-order-transactions) and [order refunds](/developer/api-reference/rest/admin/management/order-operations/payment-actions/get-order-refunds) endpoints. For information on processing order payments by API, see [Payments API Overview](/developer/docs/admin/checkout-and-cart/payments). ### Prerequisites: * [A BigCommerce store](https://support.bigcommerce.com/s/article/Starting-a-Bigcommerce-Trial) * Access token for [API authentication](/developer/docs/overview/api-fundamentals/api-accounts#api-accounts) with the following [scopes](/developer/docs/overview/api-fundamentals/api-accounts#oauth-scopes): * Orders - **modify** * Products - **read-only** * [Product](/developer/api-reference/rest/admin/catalog/products/create-product) with [variants](/developer/api-reference/rest/admin/catalog/product-variants/create-product-variant). ## Creating an order To [create an order](/developer/api-reference/rest/admin/management/orders/create-order), send a `POST` request to `/stores/{{STORE_HASH}}/v2/orders`. **`Example request: Create an order`** ```http title="Example request: Create an order" showLineNumbers={false} POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "billing_address": { "first_name": "Jane", "last_name": "Doe", "street_1": "123 Main Street", "city": "Austin", "state": "Texas", "zip": "78751", "country": "United States", "country_iso2": "US", "email": "janedoe@email.com" }, "products": [ { "name": "BigCommerce Coffee Mug", "quantity": 1, "price_inc_tax": 50, "price_ex_tax": 45 } ] } ``` > **Note** > > **Migrating historical orders** > > When migrating historical orders processed on another eCommerce platform to BigCommerce, supply the code **M-MIG** for the `external_source` field. This code will exclude historical orders from the store’s GMV/order count, which factors into pricing. > **Note** > > * The example above contains the minimum required fields for a [create order](/developer/api-reference/rest/admin/management/orders/create-order) request. > * The product ordered is a *custom* product; custom products do not exist in the catalog. > * The V2 Orders API will not trigger the typical [Order Email](https://support.bigcommerce.com/s/article/Customizing-Emails?language=en_US) when creating orders. To create an order that does trigger this email, you can instead [create a cart](/developer/api-reference/rest/admin/management/carts/carts-single/create-cart) and [convert that cart into an order](/developer/api-reference/rest/admin/management/checkouts/orders/create-order). ## Creating order shipments Once an order has products, a billing address, and a shipping address, you can create an order shipment. To [create an order shipment](/developer/api-reference/rest/admin/management/orders/order-shipments/create-order-shipments), send a `POST` request to `/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/shipments`. **`Example request: Create an order shipment`** ```http title="Example request: Create an order shipment" showLineNumbers={false} POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/shipments X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "tracking_number": "EJ958083578UK", "comments": "Janes Order", "order_address_id": "128", "shipping_provider": "", "items": [ { "order_product_id": 194, "quantity": 1 }, { "order_product_id": 195, "quantity": 1 } ] } ``` | Property | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tracking_number` | Shipping provider tracking number; used to generate tracking link | | `comments` | Optional comments | | `order_address_id` | Obtain with [Get Order Shipping Address](/developer/api-reference/rest/admin/management/orders/order-shipping-addresses/get-order-shipping-addresses) | | `shipping_provider` | Optional; used to create tracking link; see [Create Order Shipment](/developer/api-reference/rest/admin/management/orders/order-shipments/create-order-shipments) for accepted values | | `items.order_product_id` | Obtain with [Get Order Products](/developer/api-reference/rest/admin/management/orders). For non-variant products, use the `id`. | > **Note** > > * Create multiple shipments by specifying a subset of products and quantities in each `POST` request. > * Create an order shipment with product variants by using the `id` returned in each `GET` request. > * Creating order shipments triggers email notifications; adjust [Order Notification](https://support.bigcommerce.com/s/article/Customer-Order-Notifications#enable) settings in the [control panel](https://login.bigcommerce.com/deep-links/manage) to change this behavior. > * Deleting a shipment does **not** move the order out of `shipped` status. ## Changing order status Specify [order status](/developer/api-reference/rest/admin/management/orders/order-status/get-order-statuses) by including the `status_id` property in the [create order](/developer/api-reference/rest/admin/management/orders/create-order) request. To [update an order](/developer/api-reference/rest/admin/management/orders/update-order) and change its status, send a `PUT` request to `/v2/orders/{{order_id}}`. **`Example request: Change order status`** ```http title="Example request: Change order status" showLineNumbers={false} PUT https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}} X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "status_id": 2 } ``` To [get a list of order statuses](/developer/api-reference/rest/admin/management/orders/order-status/get-order-statuses), send a `GET` request to `/stores/{{STORE_HASH}}/v2/order_statuses`. #### Request **`Example request: Get order statuses`** ```http title="Example request: Get order statuses" showLineNumbers={false} GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/order_statuses X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json ``` #### Response **`Example response: Get order statuses`** ```json title="Example response: Get order statuses" showLineNumbers={false} [ { "id": 0, "name": "Incomplete", "system_label": "Incomplete", "custom_label": "Incomplete - Testing", "system_description": "An incomplete order happens when a shopper reached the payment page, but did not complete the transaction.", "order": 0 }, ... ] ``` > **Note** > > * If not specified, `status_id` defaults to `1`. > * The refunded status is neither paid nor unpaid. > * For information on changing `custom_label` in the control panel, see [Order Statuses](https://support.bigcommerce.com/s/article/Order-Statuses#rename). > * When an order is created, set to `Awaiting Fulfillment`, and then manually edited, inventory levels won't reflect a change in stock. To learn more about inventory stock settings, see [Stock Adjustment Settings](https://support.bigcommerce.com/s/article/Inventory-Tracking?language=en_US#stock-adjustment). ## Specifying order customer Specify the [customer](/developer/api-reference/rest/admin/management/customers/v3/get-customers) by including a `customer_id` in the [create order](/developer/api-reference/rest/admin/management/orders/create-order) request. **`Example request: Specify order customer`** ```http title="Example request: Specify order customer" showLineNumbers={false} POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "customer_id": 1, "billing_address": {...}, "products": [...] } ``` To [get a list of customers](/developer/api-reference/rest/admin/management/customers/v3/get-customers), send a `GET` request to `/stores/{{STORE_HASH}}/v3/customers`. **`Example request: Get a list of customers`** ```http title="Example request: Get a list of customers" showLineNumbers={false} GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/customers X-Auth-Token: {{ACCESS_TOKEN}} Accept: application/json ``` > **Note** > > Set `customer_id` to `0` to create a guest order. ## Including shipping addresses Add [shipping addresses](/developer/api-reference/rest/admin/management/orders/order-shipping-addresses/update-order-shipping-address) by including a [shipping\_address array](/developer/api-reference/rest/admin/management/orders/order-shipping-addresses/update-order-shipping-address) in the [create order](/developer/api-reference/rest/admin/management/orders/create-order) request. **`Example request: add shipping addresses`** ```http title="Example request: add shipping addresses" showLineNumbers={false} POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "billing_address": {...}, "shipping_addresses": [ { "first_name": "Rusty", "last_name": "Gates", "company": "Example LLC", "street_1": "123 Example ST", "street_2": "", "city": "Austin", "state": "Texas", "zip": "12345", "country": "United States", "country_iso2": "US", "phone": "5125550100", "email": "rusty.gates@example.com" } ], "products": [...] } ``` > **Note** > > Add multiple shipping addresses to [ship to multiple locations](#shipping-to-multiple-locations). ## Adding products Specify products from the catalog by including a products array in a `POST` request to the [Create an order](/developer/api-reference/rest/admin/management/orders/create-order) endpoint. **`Example request: Add products`** ```http title="Example request: Add products" showLineNumbers={false} POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "billing_address": {...}, "products": [ { "name": "BigCommerce Coffee Mug", # custom product "quantity": 1, "price_inc_tax": 50, "price_ex_tax": 45 }, { "product_id": 184, # product from catalog "quantity": 1, "product_options": [ { "id": 200, "value": "180" }, { "id": 230, "value": "192" } ] } ] } ``` To get the `product_options.id` and `product_options.value` of a product for the order `products` array, send the following `GET` request to [Get variants by product id](/developer/api-reference/rest/admin/catalog/product-variants/get-product-variant). See the example response that follows, or consult the [response schema](/developer/api-reference/rest/admin/catalog/product-variants/get-product-variant). #### Request **`Example request: Get product variants`** ```http title="Example request: Get product variants" showLineNumbers={false} GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/catalog/products/{{product_id}}/variants X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json ``` #### Response **`Example response: Get product variants`** ```json title="Example response: Get product variants" showLineNumbers={false} { "data": [ { "id": 421, "product_id": 184, ... "option_values": [ { "id": 180, // product_options.value "label": "Red", "option_id": 200, // product_options.id "option_display_name": "Color" }, { "id": 192, "label": "Small", "option_id": 230, "option_display_name": "T-Shirt Size" } ] } ... ] } ``` > **Note** > > * Custom products do not get added to the catalog. > * If the product's price is not specified in the [create order](/developer/api-reference/rest/admin/management/orders/create-order) request, BigCommerce's pricing service calculates the price by applying applicable currency conversions and [pricing operations](/developer/docs/admin/catalog-and-inventory/pricing/calculations) (such as [price lists](https://support.bigcommerce.com/s/article/Price-Lists) and [customer group discounts](https://support.bigcommerce.com/s/article/Customer-Groups#pricing)) to the product's catalog price; use `price_inc_tax` and `price_ex_tax` to override the calculated price. > * Marketing promotions currently do not apply to orders created with the Orders API. > * If you override `price_ex_tax` or `price_inc_tax`, override both; otherwise, order totals will not calculate correctly. > * Overriding `price_inc_tax` or `price_ex_tax` does not change variant pricing. ## Shipping to multiple locations You can create multiple shipments for orders, and each shipment can have a different `order_address_id`. #### Example 1 **`Example 1: order_address_id`** ```http title="Example 1: order_address_id" showLineNumbers={false} POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/shipments X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "order_address_id": "123", "shipping_provider": "usps", "items": [ { "order_product_id": 2, "quantity": 1 } ] } ``` #### Example 2 **`Example 2: different order_address_id`** ```http title="Example 2: different order_address_id" showLineNumbers={false} POST https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/shipments X-Auth-Token: {{ACCESS_TOKEN}} Content-Type: application/json Accept: application/json { "order_address_id": "456", "shipping_provider": "", "items": [ { "order_product_id": 5, "quantity": 1 } ] } ``` | Property | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `order_address_id` | Obtain with [Get Order Shipping Address](/developer/api-reference/rest/admin/management/orders/order-shipping-addresses/get-order-shipping-addresses) | | `shipping_provider` | Optional; used to create tracking link; see [Create Order Shipment](/developer/api-reference/rest/admin/management/orders/order-shipments/create-order-shipments) for accepted values | | `items.order_product_id` | Obtain with [Get Order Products](/developer/api-reference/rest/admin/management/orders/order-products/get-order-products). For non-variant products, use the `id`. | ## Getting shipping quotes To [get shipping quotes](/developer/api-reference/rest/admin/management/orders/order-shipping-addresses-quotes/get-order-shipping-address-shipping-quotes), send the following `GET` request. See the example response that follows, or consult the [response schema](/developer/api-reference/rest/admin/management/orders/order-shipping-addresses-quotes/get-order-shipping-address-shipping-quotes). #### Request **`Example request: Get shipping quotes`** ```http title="Example request: Get shipping quotes" showLineNumbers={false} GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/shipping_addresses/{{shipping_address_id}}/shipping_quotes X-Auth-Token: {{ACCESS_TOKEN}} Accept: application/json ``` #### Response **`Example response: Get shipping quotes`** ```json title="Example response: Get shipping quotes" showLineNumbers={false} { "id": "16", "uuid": "18aaa5eb-3c7a-4bf8-bfaa-d14d155606f1", "timestamp": "Mon, 30 Jul 2018 15:32:35 +0000", "shipping_provider_id": "bcproductbased", "shipping_provider_quote": [], "provider_code": "productfixedshipping", "carrier_code": "", "rate_code": "", "rate_id": "" } ``` Generating a quote through a shipping carrier is not supported. You can specify a shipping carrier when creating an order shipment. You can generate the quote elsewhere, then update the `shipping_cost_ex_tax` and `shipping_cost_inc_tax` for the order total to be correct. ## Getting order taxes To [get order taxes](/developer/api-reference/rest/admin/management/orders/order-taxes/get-order-taxes), send the following `GET` request. See the example response that follows, or consult the [response schema](/developer/api-reference/rest/admin/management/orders/order-taxes/get-order-taxes). #### Request **`Example request: Get order taxes`** ```http title="Example request: Get order taxes" showLineNumbers={false} GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v2/orders/{{order_id}}/taxes X-Auth-Token: {{ACCESS_TOKEN}} Accept: application/json ``` #### Response **`Example response: Get order taxes`** ```json title="Example response: Get order taxes" showLineNumbers={false} [ { "id": 13, "order_id": 138, "order_address_id": 39, "tax_rate_id": 1, "tax_class_id": 0, "name": "Tax", "class": "Default Tax Class", "rate": "8.0000", "priority": 0, "priority_amount": "17.6400", "line_amount": "17.6400" } ] ``` The response's [order tax object](/developer/api-reference/rest/admin/management/orders/order-taxes/get-order-taxes) `name` property gets set to `API Tax Override` when generated by third-party tax services like [Avalara Premium](https://www.bigcommerce.com/apps/avalara-avatax/?search=avalara). **`Example response detail: Tax object from get order taxes`** ```json title="Example response detail: Tax object from get order taxes" showLineNumbers={false} [ { "id": 13, "order_id": 138, "order_address_id": 39, "tax_rate_id": 1, "tax_class_id": 0, "name": "API Tax Override", ... } ] ``` BigCommerce submits tax documents to Avalara when an order moves from an **unpaid** status to a **paid** status and voids tax documents when an order moves from a **paid status** to an unpaid status. | Existing Status | Status Passed | Resultant Status | Avalara Tax Document Submission | | -------------------- | ------------- | ---------------- | ------------------------------- | | Any | None | `Pending` | None | | Paid or `Refunded` | Paid | Paid | None | | Unpaid or `Refunded` | Unpaid | Unpaid | None | | Paid or `Refunded` | Unpaid | Unpaid | Tax document voided | | Unpaid or `Refunded` | Paid | Paid | Tax document submitted | > **Note** > > * Abbreviated state names (ex: `CA` instead of `California`) in an order address will cause tax document submission to fail. > * You can calculate taxes using rules specified in the store unless [automatic taxes](https://support.bigcommerce.com/s/article/Automatic-Tax-Setup) are enabled. > * You can optionally override tax values by specifying `price_inc_tax` and `price_ex_tax` in an [update order request](/developer/api-reference/rest/admin/management/orders/update-order). > * If a store has [automatic tax](https://support.bigcommerce.com/s/article/Automatic-Tax-Setup) enabled, BigCommerce does not compute sales tax on orders created with the API. ## Getting order transactions To [get order transactions](/developer/api-reference/rest/admin/management/order-operations/get-order-transactions), send the following `GET` request. See the example response that follows, or consult the [response schema](/developer/api-reference/rest/admin/management/order-operations/get-order-transactions). #### Request **`Example request: Get order transactions`** ```http title="Example request: Get order transactions" GET https://api.bigcommerce.com/stores/{{STORE_HASH}}/v3/orders/{{order_id}}/transactions X-Auth-Token: {{ACCESS_TOKEN}} Accept: application/json ``` #### Response **`Example response: Get order transactions`** ```json title="Example response: Get order transactions" { "data": [ { "id": 85926313, "order_id": "121", "event": "purchase", "method": "nonce", "amount": 1, "currency": "USD", "gateway": "squarev2", "gateway_transaction_id": "pN5Kd7R9ilEI2ygBawCy7tMF|qwnAFAxRZ7tYRtIpZULg1yMF", "status": "ok", "test": false, "fraud_review": false, "reference_transaction_id": {}, "date_created": "2018-05-08T15:06:12+00:00", "avs_result": {...}, "cvv_result": {...}, "credit_card": {}, "gift_certificate": {}, "store_credit": {}, "offline": {}, "custom": {}, "payment_instrument_token": {}, "payment_method_id": "squarev2.card" } ], "meta": {...} } ``` > **Note** > > Not all payment gateways return the full card or fraud detail. Depending on the payment method, different information will be available. ## Handling refunds [Orders V3](/developer/api-reference/rest/admin/management/order-operations) exposes endpoints for managing [order refunds](/developer/api-reference/rest/admin/management/order-operations/payment-actions/get-order-refunds). For an overview on using these endpoints, see [Order Refunds in API Docs](/developer/docs/admin/checkout-and-cart/orders/refunds). ## Calculating totals Order `subtotal` and `total` calculate automatically; edits to the following properties trigger a recalculation. | Property | Type | Description | | ----------------------- | ------------ | ----------------------------------------------- | | `products` | `array[obj]` | Used to calculate shipping, taxes, and subtotal | | `shipping_cost_ex_tax` | `float` | Shipping cost, excluding tax | | `shipping_cost_inc_tax` | `float` | Shipping cost, including tax | | `handling_cost_ex_tax` | `float` | Value of handling cost, excluding tax | | `handling_cost_inc_tax` | `float` | Value of handling cost, including tax | | `wrapping_cost_ex_tax` | `float` | Value of wrapping cost, excluding tax | | `wrapping_cost_inc_tax` | `float` | Value of wrapping cost, including tax | | `billing_address` | `obj` | Used to calculate shipping and taxes | | `shipping_addresses` | `array[obj]` | Used to calculate shipping and taxes | You can override calculated values such as product prices, subtotals, and totals by sending a fixed value in the request. If you do not supply values for these properties, you will automatically calculate them based on the preset store values and tax rules. > **Note** > > * If you override `subtotal` or `total`, override both; the system will not re-calculate the other. > * To add a manual discount, overwrite the product price or `discount_amount`. ## FAQ **Is adding coupons available?** Coupon redemption is unavailable. You can not write to the `coupon_discount` field. You can add a discount to the order by using the `discount_amount`. **How do I create an order for a guest?** To specify a guest checkout, set `customer_id` to 0. **How do I set the order source?** Orders created with the API default to an `order_source` of `external`. You can set `order_source` to one of the allowed values listed in the [Create an order](/developer/api-reference/rest/admin/management/orders/create-order) reference, such as `manual` or `www`. You can also specify a value for `external_source` to identify the external system the order came from, such as a POS or accounting system. > **Note:** To publish an app that creates orders, it must include the `external_source` field on new orders, with the app's ID as the value. See [App Store Approval Requirements](/developer/docs/integrations/apps/guide/approval-requirements#functionality) to learn more. **Can I create an order with only custom products?** Yes, the store's catalog does not include products. **What is the difference between country\_ISO2 and country?** There is no requirement to specify country when you specify `country_ISO2` in the shipping and billing addresses and vice versa. **How can I take payment for an order?** You can either process payment through a third party or using the control panel. **Can I generate a shipping quote from a carrier using the API?** Not at this time. If you create an order either in the control panel or by API, it will return a 204 when trying to get a shipping quote. ## Related resources ### Articles * [Payments API Overview](/developer/docs/admin/checkout-and-cart/payments) * [Order Refunds](/developer/docs/admin/checkout-and-cart/orders/refunds) * [Order Statuses](https://support.bigcommerce.com/s/article/Order-Statuses) * [Order Notifications](https://support.bigcommerce.com/s/article/Customer-Order-Notifications) ### Endpoints * [Storefront Orders](/developer/api-reference/rest/storefront/orders) * [Orders v2](/developer/api-reference/rest/admin/management/orders) * [Orders v3](/developer/api-reference/rest/admin/management/order-operations) ### Webhooks * [Orders](/developer/docs/integrations/webhooks/event-reference#orders)