BigCommerce REST API Adapter

A drop-in compatible REST API for STOAR that mirrors BigCommerce v2 (/api/v2/orders) and v3 (/api/v3/catalog/products) — same URL paths, same RFC 2822 dates, same status_id numeric vocabulary, same { data, meta.pagination } envelope on v3, same X-Pagination-* headers on v2, same X-Auth-Token header. Existing BigCommerce client libraries (bigcommerce/api Node SDK, bigcommerce-api-php, BigCommerce Python) talk to STOAR with no modification.

This is the fourth implementation of STOAR's extensible API adapter framework (after Magento, WooCommerce, and Shopify). It demonstrates that the architecture handles two version-flavours under one adapter (v2 + v3) without duplicating any business logic.

Table of contents #

• Quick start
• Authentication
• Endpoints
  • List orders (v2)
  • Get single order (v2)
  • List order products (v2)
  • List catalog products (v3)
  • Get single catalog product (v3)
• Query parameters
• Field mapping (BigCommerce ↔ STOAR)
• Status translation
• Response shape
• Real-world example
• Error shape
• Rate limiting

Quick start #

TOKEN="5|abcdef…"     # Sanctum personal-access token with bigcommerce:admin ability

# v2 — orders
curl -H "X-Auth-Token: $TOKEN" \
     "https://app.stoar.ai/api/v2/orders?limit=5" | jq '.[] | {id, status_id, status, total_inc_tax}'

# v2 — line items for a specific order (separate sub-endpoint)
curl -H "X-Auth-Token: $TOKEN" \
     "https://app.stoar.ai/api/v2/orders/10126/products" | jq '.[].name'

# v3 — catalog products with pagination meta envelope
curl -H "X-Auth-Token: $TOKEN" \
     "https://app.stoar.ai/api/v3/catalog/products?limit=2&page=1" | jq '.meta.pagination'

# v3 — single product
curl -H "X-Auth-Token: $TOKEN" \
     "https://app.stoar.ai/api/v3/catalog/products/789"

Bearer auth (-H "Authorization: Bearer $TOKEN") is also accepted as a fallback.

Authentication #

BigCommerce's canonical auth header is X-Auth-Token: <token>. STOAR's adapter accepts it and a Bearer fallback:

Tokens are issued from STOAR's /manager/api-tokens page or programmatically via AdminUser::createToken('label', ['bigcommerce:admin']). A single token can carry every adapter's ability simultaneously (bigcommerce:admin + magento:admin + shopify:admin + woocommerce:admin).

The AuthTokenMiddleware runs before auth:sanctum and promotes X-Auth-Token into a Authorization: Bearer … header. From STOAR's perspective every BC request is a normal Sanctum-authenticated request.

OAuth client-credential flow (real BC apps go through /auth/load and /oauth2/token) is not supported.

Endpoints #

All paths are relative to /api. v2 endpoints live under /api/v2; v3 endpoints under /api/v3.

GET /api/v2/orders

List orders — flat array body + pagination headers.

Authorization: bigcommerce:admin. Query: see Query parameters.

Response:

HTTP/1.1 200 OK
X-Pagination-Total-Count: 150
X-Pagination-Page-Total:  3
Content-Type: application/json

[
  { /* order object — see Response shape */ }
]

Why headers, not envelope? This is BC v2's actual convention. v3 endpoints use the { data, meta } envelope (see catalog products below). Real BC client libraries handle both.

GET /api/v2/orders/{id}

Single order — bare object (NO envelope on v2).

Errors:

{ "status": 404, "title": "The order requested could not be found.", "type": "..." }

GET /api/v2/orders/{id}/products

Note — line items live at a SEPARATE endpoint, not embedded on the order resource. This is one of BC's bigger differences from Magento, WooCommerce, and Shopify (all of which inline line items).

Response: flat array of BC v2 line-item objects.

[
  {
    "id":              30219,
    "order_id":        10126,
    "product_id":      112238,
    "variant_id":      95589,
    "name":            "Widget",
    "sku":             "WID-1-A",
    "type":            "physical",
    "base_price":      299,
    "price_ex_tax":    299,
    "price_inc_tax":   299,
    "base_total":      897,
    "total_ex_tax":    897,
    "total_inc_tax":   897,
    "quantity":        3,
    "is_refunded":     false,
    "product_options": [],
    "..."
  }
]

GET /api/v3/catalog/products

List catalog products — v3 envelope with data + meta.pagination.

Query: see Query parameters.

Response (200):

{
  "data": [
    { /* product — see Response shape */ }
  ],
  "meta": {
    "pagination": {
      "total":         150,
      "count":         50,
      "per_page":      50,
      "current_page":  1,
      "total_pages":   3,
      "links": {
        "current": "https://.../api/v3/catalog/products?page=1&limit=50",
        "next":    "https://.../api/v3/catalog/products?page=2&limit=50"
      },
      "too_many":      false
    }
  }
}

links.previous is included on pages > 1; links.next on all but the last page.

GET /api/v3/catalog/products/{id}

Single product — v3 envelope with data (single object) + empty meta.

Response:

{
  "data": { /* product — see Response shape */ },
  "meta": {}
}

Query parameters #

Common (orders + products)

v2 orders only

v3 catalog products only

V3 supports BC's richer operator suffix syntax: id:in, price:min, etc.

Unknown operators or fields are silently ignored — same as BC behaviour.

Field mapping (BigCommerce ↔ STOAR) #

Order (v2)

Order line_item (v2 /products)

Catalog product (v3)

Catalog product variant (v3)

Status translation #

BigCommerce uses NUMERIC status_id codes plus a parallel string status field. The translator decomposes Stoar's enum into both.

Stoar → BigCommerce (rendering)

BigCommerce filter → Stoar (parsing)

?status_id=N is translated using the same lookup table. Codes that don't match anything in the map (e.g. BC's status 2 = "Manually Verified" or 6 = "Declined") fall through silently — matching BC's "no exact equivalent" behaviour. Real BC's full code map has ~14 entries; STOAR exposes the seven that map cleanly.

Product status

BigCommerce has no string status field — it uses is_visible (bool) + availability enum. Filter via ?is_visible=true for active products, ?is_visible=false for inactive.

Response shape #

v2 order — annotated

{
  "id":             456,
  "customer_id":    45,
  "date_created":   "Tue, 03 Jun 2025 04:56:43 +0000",
  "date_modified":  "Tue, 03 Jun 2025 04:56:43 +0000",
  "date_shipped":   "",
  "status_id":      11,
  "status":         "Awaiting Fulfillment",
  "subtotal_ex_tax":   100,
  "subtotal_inc_tax":  110,
  "subtotal_tax":      10,
  "total_ex_tax":      105,
  "total_inc_tax":     115,
  "total_tax":         10,
  "items_total":       2,
  "items_shipped":     0,
  "payment_method":    "stripe",
  "payment_status":    "captured",
  "refunded_amount":   0,
  "currency_code":     "EUR",
  "currency_exchange_rate":   "1.0000000000",
  "default_currency_code":    "EUR",
  "billing_address": {
    "first_name":   "Jane",
    "last_name":    "Doe",
    "company":      "",
    "street_1":     "1 Test St",
    "street_2":     "",
    "city":         "Berlin",
    "state":        "",
    "zip":          "10115",
    "country":      "Germany",
    "country_iso2": "DE",
    "phone":        "+49…",
    "email":        "[email protected]",
    "form_fields":  []
  },
  "products": {
    "url":      "https://.../api/v2/orders/456/products",
    "resource": "/orders/456/products"
  },
  "shipping_addresses": {
    "url":      "https://.../api/v2/orders/456/shippingaddresses",
    "resource": "/orders/456/shippingaddresses"
  },
  "coupons": {
    "url":      "https://.../api/v2/orders/456/coupons",
    "resource": "/orders/456/coupons"
  },
  "store_default_currency_code": "EUR",
  "channel_id":     1,
  "..."
}

v3 catalog product — abbreviated

{
  "data": {
    "id":                  789,
    "name":                "Widget",
    "type":                "physical",
    "sku":                 "WID-1",
    "description":         "<p>A great widget</p>",
    "weight":              0.5,
    "price":               99.99,
    "sale_price":          0,
    "retail_price":        0,
    "calculated_price":    99.99,
    "categories":          [5],
    "is_visible":          true,
    "is_featured":         true,
    "availability":        "available",
    "inventory_tracking":  "product",
    "inventory_level":     42,
    "page_title":          "Widget – buy now",
    "custom_url": {
      "url":             "/widget",
      "is_customized":   false,
      "create_redirect": false
    },
    "images": [
      { "id": 0, "image_file": "products/widget.webp", "is_thumbnail": true, "sort_order": 0, "url_thumbnail": "products/widget.webp", "url_zoom": "products/widget.webp", "..." }
    ],
    "variants": [
      { "id": 12, "product_id": 789, "sku": "WID-RED", "price": 99.99, "inventory_level": 22, "purchasing_disabled": false, "..." }
    ]
  },
  "meta": {}
}

Real-world example #

GET /api/v2/orders/10126 against production. Same Stoar order featured in Magento, WooCommerce, and Shopify — rendered in BC v2 shape. PII anonymised.

{
  "id":                 10126,
  "customer_id":        5794,
  "date_created":       "Tue, 03 Jun 2025 04:56:43 +0000",
  "date_modified":      "Tue, 03 Jun 2025 04:56:43 +0000",
  "date_shipped":       "",
  "status_id":          11,
  "status":             "Awaiting Fulfillment",
  "subtotal_ex_tax":    936.98,
  "subtotal_inc_tax":   936.98,
  "subtotal_tax":       0,
  "shipping_cost_ex_tax":  0,
  "shipping_cost_inc_tax": 0,
  "shipping_cost_tax":     0,
  "total_ex_tax":       936.98,
  "total_inc_tax":      936.98,
  "total_tax":          0,
  "items_total":        5,
  "items_shipped":      0,
  "payment_method":     "payid",
  "payment_provider_id":null,
  "payment_status":     "captured",
  "refunded_amount":    0,
  "order_is_digital":   false,
  "currency_id":        1,
  "currency_code":      "USD",
  "currency_exchange_rate":   "1.0000000000",
  "default_currency_id":      1,
  "default_currency_code":    "USD",
  "staff_notes":        "",
  "customer_message":   "",
  "discount_amount":    0,
  "coupon_discount":    0,
  "shipping_address_count": 1,
  "is_deleted":         false,
  "ebay_order_id":      "0",
  "cart_id":            null,
  "billing_address": {
    "first_name":   "Jane",
    "last_name":    "Doe",
    "company":      "",
    "street_1":     "1 Example Street",
    "street_2":     "",
    "city":         "Phoenix",
    "state":        "AZ",
    "zip":          "85001",
    "country":      "United States",
    "country_iso2": "US",
    "phone":        "+1-555-0100",
    "email":        "",
    "form_fields":  []
  },
  "products": {
    "url":      "https://app.stoar.ai/api/v2/orders/10126/products",
    "resource": "/orders/10126/products"
  },
  "shipping_addresses": {
    "url":      "https://app.stoar.ai/api/v2/orders/10126/shippingaddresses",
    "resource": "/orders/10126/shippingaddresses"
  },
  "coupons": {
    "url":      "https://app.stoar.ai/api/v2/orders/10126/coupons",
    "resource": "/orders/10126/coupons"
  },
  "store_default_currency_code": "USD",
  "store_default_to_transactional_exchange_rate": "1.0000000000",
  "custom_status":      "Awaiting Fulfillment",
  "channel_id":         1,
  "ip_address":         "",
  "ip_address_v6":      "",
  "geoip_country":      "",
  "geoip_country_iso2": "",
  "is_email_opt_in":    false,
  "credit_card_type":   null,
  "order_source":       "www",
  "external_source":    null,
  "external_id":        null,
  "external_merchant_id":null,
  "tax_provider_id":    "",
  "customer_locale":    "en",
  "external_order_id":  ""
}

Caveats integrators should know

Error shape #

BigCommerce uses an RFC 7807-style envelope:

{
  "status": 404,
  "title":  "The order requested could not be found.",
  "type":   "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes",
  "errors": { "<field>": "..." }
}

type always points to BC's status-codes documentation page. errors is only present on validation failures (400).

Rate limiting #

The same api-rest Sanctum-token-keyed throttle that protects all other adapters protects BC routes. Configure both the threshold and the master switch at /manager/api-settings. When triggered, the response uses BC's RFC 7807 envelope:

HTTP/1.1 429 Too Many Requests
X-Rate-Limit-Time-Reset-Ms: 60000
X-Rate-Limit-Requests-Left: 0
Content-Type: application/json

{
  "status": 429,
  "title":  "Too many requests.",
  "type":   "https://developer.bigcommerce.com/api-docs/getting-started/api-status-codes"
}

The X-Rate-Limit-* headers match BC's documented behaviour. Real BC returns more headers and uses second-resolution windows; STOAR uses Laravel's minute window — close enough for client-library compatibility.

A single Sanctum token used across all four adapters shares one bucket — see Magento's Rate limiting section for the configuration UI walkthrough.

See also #

• app/Api/Adapters/BigCommerce/Support/StatusTranslator.php — bidirectional vocabulary mapping
• BigCommerce REST API reference — the upstream spec this adapter mirrors