BigCommerce Order Management
Before writing code
Fetch live docs:
- Web-search
site:developer.bigcommerce.com rest orders for Orders API reference
- Web-search
bigcommerce order api v2 v3 for endpoint availability
- Web-search
bigcommerce order status list for status definitions
API Endpoints
V2 Orders (Primary)
Orders are primarily managed via V2 API:
| Endpoint |
Methods |
Description |
/v2/orders |
GET, POST, PUT |
Orders CRUD |
/v2/orders/{id}/products |
GET |
Order line items |
/v2/orders/{id}/shipping_addresses |
GET |
Shipping addresses |
/v2/orders/{id}/coupons |
GET |
Applied coupons |
/v2/orders/{id}/shipments |
GET, POST, PUT, DELETE |
Shipments |
/v2/orders/{id}/taxes |
GET |
Tax details |
/v2/order_statuses |
GET |
Available order statuses |
V3 Order Extensions
| Endpoint |
Description |
/v3/orders/{id}/metafields |
Order metafields |
/v3/orders/{id}/payment_actions |
Payment actions (capture, void) |
/v3/orders/settings |
Order-level settings |
/v3/orders/{id}/transactions |
Payment transactions |
Order Lifecycle
Status Flow
Incomplete → Pending → Awaiting Payment → Awaiting Fulfillment
→ Partially Shipped → Shipped → Completed
→ Awaiting Pickup → Picked Up
→ Cancelled / Declined / Refunded / Disputed
Standard Statuses
| ID |
Status |
Description |
| 0 |
Incomplete |
Checkout not completed |
| 1 |
Pending |
Awaiting processing |
| 2 |
Shipped |
All items shipped |
| 3 |
Partially Shipped |
Some items shipped |
| 4 |
Refunded |
Fully refunded |
| 5 |
Cancelled |
Order cancelled |
| 6 |
Declined |
Payment declined |
| 7 |
Awaiting Payment |
Payment not yet received |
| 8 |
Awaiting Pickup |
Ready for customer pickup |
| 9 |
Awaiting Shipment |
Awaiting fulfillment |
| 10 |
Completed |
Order completed |
| 11 |
Awaiting Fulfillment |
Ready to be fulfilled |
| 12 |
Manual Verification Required |
Payment needs manual review |
| 13 |
Disputed |
Payment dispute opened |
| 14 |
Partially Refunded |
Partial refund issued |
Custom Statuses
Create custom statuses via admin or API — they map to one of the standard status groups for reporting.
Order Structure
Order Fields
Key fields returned by GET /v2/orders/{id}:
id — order number
status_id — current status
status — status label
subtotal_inc_tax, subtotal_ex_tax
total_inc_tax, total_ex_tax
discount_amount
shipping_cost_inc_tax, shipping_cost_ex_tax
items_total — total number of items
payment_method — payment provider
currency_code
billing_address — billing address object
customer_id — associated customer
date_created, date_modified
Line Items
GET /v2/orders/{id}/products returns:
product_id, variant_id
name, sku, quantity
price_inc_tax, price_ex_tax
total_inc_tax, total_ex_tax
product_options — selected options
Creating Orders
Server-Side Order Creation
POST /v2/orders with:
customer_id or billing_address
products array with product_id, quantity, and optionally price_inc_tax
status_id
shipping_addresses array
Useful for: POS integrations, phone orders, order imports.
Shipments
Creating Shipments
POST /v2/orders/{id}/shipments:
{
"tracking_number": "1Z999AA10123456784",
"shipping_method": "UPS Ground",
"shipping_provider": "ups",
"items": [
{ "order_product_id": 15, "quantity": 1 }
]
}
Shipment Flow
- Create shipment with tracking info and items
- Order status auto-updates to "Partially Shipped" or "Shipped"
- Customer receives shipping notification email
- Tracking info displayed in customer order history
Refunds
Creating Refunds
POST /v3/orders/{id}/payment_actions/refund:
{
"items": [
{
"item_type": "PRODUCT",
"item_id": 123,
"quantity": 1,
"reason": "Customer requested return"
}
]
}
Refund Types
- Full refund — refund the entire order amount
- Partial refund — refund specific items or custom amount
- Line-item refund — refund specific products with quantities
Order Metafields
Store custom data on orders (V3):
POST /v3/orders/{id}/metafields
- Used for: external IDs, fulfillment notes, integration data
namespace + key = unique per order
Querying Orders
Filters
min_id / max_id — ID range
min_date_created / max_date_created — date range
status_id — filter by status
customer_id — filter by customer
email — filter by customer email
payment_method — filter by payment provider
is_deleted — include/exclude deleted orders
Pagination
V2 uses page and limit parameters, plus Link headers for navigation.
Best Practices
- Use webhooks (
store/order/created, store/order/statusUpdated) for real-time order processing
- Fetch order details via API after receiving webhook (webhooks only contain the order ID)
- Handle all order statuses — don't assume a linear flow
- Use metafields for integration-specific data, not order notes
- Create shipments with tracking info for best customer experience
- Process refunds through the API for accurate financial records
- Implement idempotency — check if an order was already processed before acting
Fetch the BigCommerce Orders API reference for exact endpoint paths, request/response schemas, and status definitions before implementing.
1---2name: bc-orders3description: Work with BigCommerce orders — order lifecycle, statuses, line items, shipments, refunds, order metafields, and fulfillment. Use when building order management integrations or processing orders programmatically.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/bc-orders7---89# BigCommerce Order Management1011## Before writing code1213**Fetch live docs**:141. Web-search `site:developer.bigcommerce.com rest orders` for Orders API reference152. Web-search `bigcommerce order api v2 v3` for endpoint availability163. Web-search `bigcommerce order status list` for status definitions1718## API Endpoints1920### V2 Orders (Primary)2122Orders are primarily managed via V2 API:2324| Endpoint | Methods | Description |25|----------|---------|-------------|26| `/v2/orders` | GET, POST, PUT | Orders CRUD |27| `/v2/orders/{id}/products` | GET | Order line items |28| `/v2/orders/{id}/shipping_addresses` | GET | Shipping addresses |29| `/v2/orders/{id}/coupons` | GET | Applied coupons |30| `/v2/orders/{id}/shipments` | GET, POST, PUT, DELETE | Shipments |31| `/v2/orders/{id}/taxes` | GET | Tax details |32| `/v2/order_statuses` | GET | Available order statuses |3334### V3 Order Extensions3536| Endpoint | Description |37|----------|-------------|38| `/v3/orders/{id}/metafields` | Order metafields |39| `/v3/orders/{id}/payment_actions` | Payment actions (capture, void) |40| `/v3/orders/settings` | Order-level settings |41| `/v3/orders/{id}/transactions` | Payment transactions |4243## Order Lifecycle4445### Status Flow4647```48Incomplete → Pending → Awaiting Payment → Awaiting Fulfillment49 → Partially Shipped → Shipped → Completed50 → Awaiting Pickup → Picked Up51 → Cancelled / Declined / Refunded / Disputed52```5354### Standard Statuses5556| ID | Status | Description |57|----|--------|-------------|58| 0 | Incomplete | Checkout not completed |59| 1 | Pending | Awaiting processing |60| 2 | Shipped | All items shipped |61| 3 | Partially Shipped | Some items shipped |62| 4 | Refunded | Fully refunded |63| 5 | Cancelled | Order cancelled |64| 6 | Declined | Payment declined |65| 7 | Awaiting Payment | Payment not yet received |66| 8 | Awaiting Pickup | Ready for customer pickup |67| 9 | Awaiting Shipment | Awaiting fulfillment |68| 10 | Completed | Order completed |69| 11 | Awaiting Fulfillment | Ready to be fulfilled |70| 12 | Manual Verification Required | Payment needs manual review |71| 13 | Disputed | Payment dispute opened |72| 14 | Partially Refunded | Partial refund issued |7374### Custom Statuses7576Create custom statuses via admin or API — they map to one of the standard status groups for reporting.7778## Order Structure7980### Order Fields8182Key fields returned by `GET /v2/orders/{id}`:83- `id` — order number84- `status_id` — current status85- `status` — status label86- `subtotal_inc_tax`, `subtotal_ex_tax`87- `total_inc_tax`, `total_ex_tax`88- `discount_amount`89- `shipping_cost_inc_tax`, `shipping_cost_ex_tax`90- `items_total` — total number of items91- `payment_method` — payment provider92- `currency_code`93- `billing_address` — billing address object94- `customer_id` — associated customer95- `date_created`, `date_modified`9697### Line Items9899`GET /v2/orders/{id}/products` returns:100- `product_id`, `variant_id`101- `name`, `sku`, `quantity`102- `price_inc_tax`, `price_ex_tax`103- `total_inc_tax`, `total_ex_tax`104- `product_options` — selected options105106## Creating Orders107108### Server-Side Order Creation109110`POST /v2/orders` with:111- `customer_id` or `billing_address`112- `products` array with `product_id`, `quantity`, and optionally `price_inc_tax`113- `status_id`114- `shipping_addresses` array115116Useful for: POS integrations, phone orders, order imports.117118## Shipments119120### Creating Shipments121122`POST /v2/orders/{id}/shipments`:123```json124{125 "tracking_number": "1Z999AA10123456784",126 "shipping_method": "UPS Ground",127 "shipping_provider": "ups",128 "items": [129 { "order_product_id": 15, "quantity": 1 }130 ]131}132```133134### Shipment Flow1351361. Create shipment with tracking info and items1372. Order status auto-updates to "Partially Shipped" or "Shipped"1383. Customer receives shipping notification email1394. Tracking info displayed in customer order history140141## Refunds142143### Creating Refunds144145`POST /v3/orders/{id}/payment_actions/refund`:146```json147{148 "items": [149 {150 "item_type": "PRODUCT",151 "item_id": 123,152 "quantity": 1,153 "reason": "Customer requested return"154 }155 ]156}157```158159### Refund Types160161- **Full refund** — refund the entire order amount162- **Partial refund** — refund specific items or custom amount163- **Line-item refund** — refund specific products with quantities164165## Order Metafields166167Store custom data on orders (V3):168- `POST /v3/orders/{id}/metafields`169- Used for: external IDs, fulfillment notes, integration data170- `namespace` + `key` = unique per order171172## Querying Orders173174### Filters175176- `min_id` / `max_id` — ID range177- `min_date_created` / `max_date_created` — date range178- `status_id` — filter by status179- `customer_id` — filter by customer180- `email` — filter by customer email181- `payment_method` — filter by payment provider182- `is_deleted` — include/exclude deleted orders183184### Pagination185186V2 uses `page` and `limit` parameters, plus `Link` headers for navigation.187188## Best Practices189190- Use webhooks (`store/order/created`, `store/order/statusUpdated`) for real-time order processing191- Fetch order details via API after receiving webhook (webhooks only contain the order ID)192- Handle all order statuses — don't assume a linear flow193- Use metafields for integration-specific data, not order notes194- Create shipments with tracking info for best customer experience195- Process refunds through the API for accurate financial records196- Implement idempotency — check if an order was already processed before acting197198Fetch the BigCommerce Orders API reference for exact endpoint paths, request/response schemas, and status definitions before implementing.