Changelog

GraphQL Schema Updates

New checkout error types, locale fields, cart option identifiers, and B2B terminology updates across the Storefront and B2B GraphQL schemas.

Storefront GraphQL

• Structured checkout errors expanded — new CheckoutBillingAddressError and CheckoutCouponError types with COUPON_EXPIRED, COUPON_INELIGIBLE, COUPON_INVALID, COUPON_INVALID_LOCATION, COUPON_MIN_PURCHASE, COUPON_MODIFICATION_NOT_ALLOWED, and COUPON_NOT_APPLICABLE codes on CheckoutErrorCode
• Checkout result errors — new CompleteCheckoutError and UpdateCheckoutError unions surfaced through errors on CompleteCheckoutResult and UpdateCheckoutResult; CreateCheckoutError now includes CheckoutCouponError
• Locale alternates — new locales field on BlogIndexPage, BlogPost, Brand, and Category for localized alternate paths and URLs
• Cart option identifiers — new attributeId field on every CartSelectedOption variant and addedByAttributeId on CartPhysicalItem and CartDigitalItem to correlate items back to the option that produced them

B2B GraphQL

• B2B Edition rebrand — schema descriptions referencing BundleB2B updated to B2BEdition across userCompany, BCInfomation, OrderType, OrderedProductType, CompanyUserInfoType, CustomerInfoType, StoreSitesType, and UserAuthResultType

For schema details, browse the Storefront GraphQL API reference and the B2B GraphQL API reference.

Catalyst Core Updates: Private Tokens and the GraphQL Proxy

Updates to the Catalyst Core course document how Catalyst authenticates GraphQL requests with private storefront tokens and how it proxies client-side requests.

• Set Up a Catalyst Project lab — clarifies that BIGCOMMERCE_STOREFRONT_TOKEN is a private GraphQL Storefront API token and links to the Create Private Token endpoint
• Environment variables — adds BIGCOMMERCE_STOREFRONT_UNAUTHENTICATED_TOKEN, the private token limited to the “Unauthenticated” scope used to proxy client-side GraphQL requests
• The API Client lesson — adds a GraphQL Proxy section explaining how Catalyst proxies browser POST /graphql requests to BigCommerce without exposing a storefront token

For details, see the Catalyst Core course.

B2B Core course GraphQL lesson streamlined

The GraphQL overview lesson in the B2B Core course now points to the dedicated B2B GraphQL API course for full coverage.

• Slimmer overview — trims the in-lesson basics, authentication, and example-request sections now covered in depth by the dedicated course.
• Two storefront GraphQL APIs — clarifies when to use the B2B GraphQL API versus the standard GraphQL Storefront API for B2B operations.
• Course link — adds a link to the B2B GraphQL API course under Resources.

For details, see the B2B GraphQL API course.

Improved Stencil schemas reference documentation

Thanks to user feedback, the Stencil schemas reference has been rewritten so theme developers can answer the question “what objects can I actually use on this template?” without scanning the whole page.

• Scannable property docs — every object’s properties are now rendered as ParamField rows with collapsible Expandable sections for nested objects and arrays.
• Globals-first ordering — the Global objects table (available on every template) appears before the Page-specific context table, so the always-available baseline is the first thing you see.
• Expanded page-context table — added rows for checkout.html, page-contact-form.html, {{pagination}} on blog.html, and {{faceted_search}} on search.html. A new callout names common routes (auth/login.html, errors.html, etc.) that receive only the globals, so gaps in the table aren’t read as omissions.
• Runtime inspection tip — a callout at the top links to ?debug=context so you can dump the live context object for any URL instead of guessing from docs.
• theme_settings rewritten for non-Cornerstone themes — a new warning callout explains that the documented keys are Cornerstone defaults, not a fixed schema, and new subsections show how to access values via dot notation and how to find the real key list for your theme via config.json and ?debug=context.
• Per-object metadata — every object now leads with a uniform Scope / Available on / Handlebars expression block instead of the previous mix of floating type hints.

Keep the feedback coming — every piece of feedback we receive directly contributes to the improvement of our docs. Use the Was this page helpful? widget at the bottom of any docs page, and we’ll keep iterating.

For details, see the Stencil schemas reference.

API Explorer now returns JSON for v2 REST endpoints

Thanks to user feedback, REST /v2/ endpoints in the API Explorer now return JSON responses instead of XML, matching the Accept: application/json header advertised in the request.

• Path-level header parameters now inherit correctly — operations defined under a path in the OpenAPI specs pick up Accept and other header parameters declared at the path level, so v2 responses render as JSON in the Explorer.
• No spec changes required on our side — the fix landed in the Fern platform; existing v2 specs render correctly without edits.

For an example, try List Customers (v2) in the API Explorer.

API Explorer now renders your store’s hash as a path parameter

Thanks to user feedback, store_hash now appears as a first-class, highlighted input in the API Explorer for the majority of REST endpoints — matching how order_id, product_id, and other resource identifiers already work.

• Highlighted in the request URL — {store_hash} renders with the same accent styling as other path parameters in the URL bar at the top of every Explorer page.

  

• Dedicated input field — store_hash now appears in the Path parameters section, so you can fill it in like any other parameter. Previously, you had to edit the URL string in the Explorer directly to set your store’s hash.

  

• Generated code snippets updated — cURL, JavaScript, and Python snippets on the right rail pick up the value you enter, no manual substitution required.

This update covers every REST endpoint in the API Reference.

For an example, see List Products.

Price Lists Records API: required fields corrected

Thanks to user feedback, we’ve corrected the API reference for the Create or Update Batch of Price Lists Records endpoint (PUT /pricelists/records). Several fields the server enforces as required were previously marked as optional.

• price_list_id — now correctly marked Required
• currency — now correctly marked Required
• variant_id or sku — clarified that exactly one of these is required to identify the variant
• Operation description — added a note summarizing the required fields

For details, see Create or Update Batch of Price Lists Records.

Product Modifiers spec accuracy improvements

Thanks to user feedback, we’ve improved the accuracy and consistency of the Product Modifiers OpenAPI spec so request and response shapes now match the live API exactly.

• Aligned UPDATE with CREATE — PUT /catalog/products/{product_id}/modifiers/{modifier_id} and the option_values update schema now share the same field set and types as their CREATE counterparts.
• Scoped option_value required fields to POST — label and sort_order are required only on create, matching the partial-update behavior of PUT.
• Corrected the Create Product Modifier response — the 200 response now refs the modifier schema directly under data, matching the live API and the GET/UPDATE responses (previously wrapped under a spurious data.items array).
• Documented adjusters.image_url as read-only — sending it on POST/PUT returns HTTP 500. The field is set via the dedicated Create Product Modifier Image endpoint, which is now cross-linked from the relevant operations.
• Tightened multipart upload schema — Create Product Modifier Image now declares image_file as required at the schema level instead of in prose.
• Removed noise from rendered docs — dropped redundant “Required/Read-Only Fields” prose blocks (Fern already renders these inline), and removed meaningless full-int32 min/max bounds on sort_order that were rendering as a confusing range pill.

For details, see the Product Modifiers reference.

GraphQL Schema Updates

New types, fields, and enums across the Storefront and B2B GraphQL schemas.

Storefront GraphQL

• Structured checkout errors — new CartError, CartLineItemError, CheckoutShippingConsignmentError, and CheckoutTaxError types with CartErrorCode, CheckoutErrorCode, and CheckoutTaxErrorCode enums, surfaced through the CreateCheckoutError union on CreateCheckoutResult.errors
• Extra field values — new ExtraFieldValue interface and TextExtraFieldValue, NumberExtraFieldValue, MultilineTextExtraFieldValue, and MultipleChoiceExtraFieldValue implementations for B2B extra fields
• Inventory by location — new ProductInventoryByLocation, ProductLocationConnection, and byLocation field on ProductInventory with location ID, code, type, and distance filtering
• Search suggestions — new SearchProductSuggestion and SearchProductSuggestionResult types and suggestions field on SearchProducts for spelling corrections and autocomplete
• Filter item counts — new displayItemsCount field on BrandSearchFilter, CategorySearchFilter, and ProductAttributeSearchFilter
• Metafield description — new description field on Metafields
• Gift certificate entity ID — new entityId field on CheckoutGiftCertificate
• Backorder messaging (alpha) — new backorderShippingExpectationMessage field on orders and backorderMessage field on OrderPhysicalLineItem

B2B GraphQL

• Catalog quick product inventory — new inventoryTracking, availableToSell, unlimitedBackorder, totalOnHand, and backorderMessage fields on CatalogQuickProductType
• Order backorder snapshot removed — backorderSnapshot field removed from OrderType

For schema details, browse the Storefront GraphQL API reference and the B2B GraphQL API reference.

B2B sales rep company authorization

Storefront sales reps (Super Admins) can now only access companies they are directly assigned to. Assignments do not traverse the Account Hierarchy — assigning a sales rep to a parent Company does not grant access to its subsidiaries.

• Scoped access — the storefront Companies and Users API enforces sales rep–to–company assignment on requests targeting a specific companyId
• Unassigned company — returns 403 Permission denied; a non-integer companyId returns 400 Invalid companyId
• Assigning companies — use the Server-to-Server Super Admin API to assign a sales rep to each Company they need to act on, including subsidiaries

For details, see the Super Admin overview.