Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 28 ยท REST APIs

Orders, Customers and the V2/V3 Split

Use the BigCommerce V2 Orders API and V3 Customers API: order statuses, consignments, filters, pagination, rate limits, 429 responses and retries with backoff.

Orders and customers are the data merchants care about most, and integrations that touch them (ERP sync, shipping, email tools, reporting) are common. In BigCommerce these two domains live in different API generations: orders are mostly V2, while customers are V3. This lesson shows how to read both, how order statuses work, and how to survive the platform's rate limits with retries and backoff.

The real calls are read-only because they need a store and a token. The runnable stand-in is a retrying client talking to a fake rate-limited API in Node.js. The fake uses a virtual clock so the output is identical on every run; the real API uses real time and its own limits.

The V2 orders API

Orders are listed and read at /v2/orders. The V2 API uses page and limit for paging (with a maximum limit), and it returns a plain JSON array without the V3 data and meta envelope. Some responses for empty lists return 204 No Content rather than an empty array, so handle an empty body. Read-only examples:

TEXT
GET /v2/orders?limit=50&page=1
GET /v2/orders?min_date_created=2025-01-01T00:00:00Z&status_id=11
GET /v2/orders/{order_id}
GET /v2/orders/{order_id}/products
GET /v2/orders/{order_id}/shipping_addresses
GET /v2/orders/{order_id}/shipments
PUT /v2/orders/{order_id}      (for example to change the status)

Useful filters include min_date_created, max_date_created, min_date_modified, status_id and customer_id. For a nightly job, filtering on min_date_modified is much cheaper than reading every order. The V2 pricing fields are strings with decimals, so parse them carefully and convert to integer minor units before doing arithmetic (Money as Integers).

Newer order-related endpoints sit in V3, for example order transactions, refunds and some order metafields. When a task is "read the order", you will often use V2 for the order itself and V3 for money-related details. Always look in the reference for the specific data you need.

Order statuses

An order has a numeric status_id and a status name. The default statuses are stable and worth memorizing:

id Status
0 Incomplete
1 Pending
2 Shipped
3 Partially Shipped
4 Refunded
5 Cancelled
6 Declined
7 Awaiting Payment
8 Awaiting Pickup
9 Awaiting Shipment
10 Completed
11 Awaiting Fulfillment
12 Manual Verification Required
13 Disputed
14 Partially Refunded

Display names can be customized or localized by a merchant, so rely on the ids instead of the names. A typical fulfillment integration looks for orders in Awaiting Fulfillment (11), creates a shipment (which moves the order to Shipped or Partially Shipped), and avoids touching orders that are Incomplete, Declined or Awaiting Payment. The idea of states and legal transitions is explained in The Order Lifecycle and State Machines; BigCommerce's statuses are one concrete instance of it.

Consignments and shipping addresses

An order can ship to more than one address. In the checkout API this is modeled with consignments: each consignment has a shipping address, the line items going there and the chosen shipping option. In the orders API you see the result as several shipping addresses, each with its own items and shipping method. A fulfillment system should therefore iterate over shipping_addresses and match the order's products to each address, instead of assuming a single destination. You will meet the checkout side in Carts and the Checkout API.

The V3 customers API

Customers are managed at /v3/customers. This is a normal V3 endpoint with the data and meta envelope, and filters with the :in suffix:

TEXT
GET  /v3/customers?email:[email protected]
GET  /v3/customers?id:in=11,12&include=addresses
POST /v3/customers          (body is an array of customers)
PUT  /v3/customers          (body is an array; each needs an id)

Creating and updating customers takes an array, even for one customer, so you can send a few at a time. Looking a customer up by email with email:in is the usual way to find out whether you need to create or update, which is the "upsert" pattern. Customer data is personal data: request only the fields you need and follow Privacy and Compliance.

flowchart LR
    A["Integration"] -->|"GET /v2/orders<br/>status_id=11"| B["Orders (V2)"]
    A -->|"GET /v3/customers<br/>id:in=..."| C["Customers (V3)"]
    B --> D["Join in your code<br/>by customer_id"]
    C --> D

Two API generations, joined in your own code on the customer id.

Rate limits and 429

Every API has limits so that one client cannot overload a store. When you exceed them, the platform answers 429 Too Many Requests. Rate-limit headers help you slow down before that: X-Rate-Limit-Requests-Left tells you how many requests remain in the current window and X-Rate-Limit-Time-Reset-Ms tells you how many milliseconds until the window resets. The related X-Rate-Limit-Requests-Quota and X-Rate-Limit-Time-Window-Ms headers describe the allowance. The exact limits depend on the plan and endpoint and can change, so a client must read the headers and not hard-code numbers.

A correct client does two things. It respects the reset time on a 429 (wait at least that long) and it retries with backoff for transient failures such as 429, 500, 502, 503 and 504, while it does not retry client errors like 400, 401, 403 or 404, because they will fail again. Adding jitter (a small random delay) prevents many workers from retrying at the same instant. If you also create resources, combine retries with idempotent design (Idempotency), because a retried POST can create a duplicate when the first attempt actually succeeded but the response was lost.

A retrying client against a fake API

The stand-in below includes a fake API that allows 3 requests per window and then returns 429 with a reset time, and a client that retries with the reset header or, failing that, exponential backoff. Time is simulated with a counter, so nothing really waits. The fake also returns a 503 once to show a transient error. This is a model of the behavior, not BigCommerce's actual limit values.

Node.js Retry with backoff against a rate-limited API

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You can read the story in the log: three requests succeed, the fourth hits the limit (429), and the client sleeps exactly until the reset time. The next attempt meets a transient 503, so the client backs off for 200 ms and then succeeds. Nothing is lost, and the client never hammers the API.

Combining orders and customers

The last stand-in joins two fake lists the way an integration would: fetch orders awaiting fulfillment (V2 style, plain array), fetch their customers (V3 style, envelope, id:in filter) in one request and merge. It also converts decimal strings to integer cents before summing.

Node.js Join V2 orders with V3 customers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Ana has two orders worth 54.75 in total. One customer lookup served both orders, which keeps your request count low and your rate-limit budget healthy.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which API generation holds the main orders endpoints?

    Orders are mostly V2, while customers, catalog and carts are V3. Expect to combine both.
  2. 2. Which order status id usually means "ready for the warehouse to ship"?

    11 is Awaiting Fulfillment. 0 is Incomplete, 5 is Cancelled and 13 is Disputed.
  3. 3. You receive a 429 with X-Rate-Limit-Time-Reset-Ms: 700. What should the client do?

    The header says when the window resets. Waiting that long respects the limit.
  4. 4. Which failures should a client NOT retry?

    Authentication and permission errors will fail again until you change the token or its scopes.
  5. 5. Why is retrying a POST riskier than retrying a GET?

    A lost response hides a success. Idempotent design or a lookup before create prevents duplicates.

Summary

  • Orders are mostly V2 (plain arrays, page/limit), customers are V3 (data/meta, :in filters, array bodies).
  • Learn the numeric order statuses; 11 means Awaiting Fulfillment.
  • Orders can ship to several addresses, so iterate over shipping addresses.
  • Read the rate-limit headers, honor the reset time on 429, and retry only transient errors with backoff and jitter.
  • Convert decimal money to integer cents before arithmetic, and join orders and customers in your own code.

Next: GraphQL Storefront API