Changelog

BigCommerce Payments order details sent to PayPal

We are beginning to roll out a fix to the order details that BigCommerce Payments sends to PayPal, so you may notice changes to how orders appear in PayPal, Klarna, and Afterpay over the coming weeks.

• Line items for every payment method: orders paid by card, PayPal, Apple Pay, Google Pay, Venmo, and the other BigCommerce Payments methods include their line items with per-item tax, as Klarna, Afterpay, and Ratepay orders already did. Previously, some orders were sent without line items, such as orders paid partly with a gift certificate or orders with a custom fee.
• Shipping tax shown with shipping: tax charged on shipping appears in the shipping amount instead of as a separate handling charge.
• Fractional-cent discounts: orders with a discount that does not divide evenly into cents, such as a percentage discount on shipping, keep their full amount breakdown instead of losing it to a one-cent rounding difference.

The amount charged to the shopper does not change.

Same-domain checkout for auto-generated hostnames

Catalyst Native Hosting channels on an auto-generated hostname can now keep checkout on the storefront’s domain. A storefront on <your-project>.catalyst-sandbox.store has a matching checkout hostname, c.<your-project>.catalyst-sandbox.store, and setting it as the channel’s checkout URL is what provisions it: BigCommerce creates its DNS record and issues its certificate in response. This replaces the earlier guidance that these channels could only use the shared checkout domain.

• Offered after a deploy. After a successful interactive catalyst deploy, the CLI offers to point the storefront’s channel at the deployment, then to move checkout onto the c. hostname. Both prompts default to No, a declined offer is saved per channel in .bigcommerce/project.json and not made again, and nothing is asked when the terminal isn’t interactive or CI is set.
• deploy --update-checkout-url sets the c. hostname directly on an auto-generated hostname, then waits for its certificate. If none is issued within six minutes, it removes the checkout URL again so checkout falls back to the shared domain rather than staying broken.
• channels update offers the same move after it points a channel at an auto-generated hostname, and --checkout-url https://c.<your-project>.catalyst-sandbox.store sets it directly.
• The checkout hostname belongs to the channel. Deleting the project leaves it in place; removing the channel’s checkout URL, changing its site URL, or deleting the channel releases it.

Storefronts on a custom domain are unchanged: point a checkout subdomain at BigCommerce and set it with channels update --checkout-url.

For details, see Checkout Domains.

Docs MCP Server: clearer scope and Claude Code setup

Thanks to user feedback, the page for connecting AI tools to the BigCommerce docs is now Docs MCP Server, says up front what the server does, and clarifies the Claude Code setup instructions.

• Docs search only. The server lets your agent search and reference the documentation. It has no access to store or account data. If you’re looking for an MCP server that interacts with your storefront, see the BigCommerce MCP Server (Beta). For everything else, use the REST and GraphQL APIs.
• Claude Code setup in three steps. Copy, run, confirm, with the single-project and every-project (--scope user) commands shown side by side so you pick before you run.
• Buttons described accurately. Connect to Cursor installs the server directly. Connect to Claude Code copies the install command for you to paste.

GraphQL Schema Updates

The Storefront GraphQL currencyCode enum now covers the full ISO 4217 code list, including precious metals, supranational units, and special-purpose codes.

Storefront GraphQL

• New currency codes: the currencyCode enum adds 15 ISO 4217 values. The enum is used wherever the schema accepts or returns a typed currency code, including the currency and currencies fields on Site, the defaultCurrency field on CurrencySettings, and the currencyCode argument on Product.prices, Variant.prices, Category.shopByPriceRanges, and Settings.giftCertificates.
  • National currency: VES (Venezuelan bolívar soberano).
  • Caribbean guilder: XCG, already available in the Admin and Account GraphQL schemas.
  • Precious metals: XAG (silver), XAU (gold), XPD (palladium), and XPT (platinum).
  • Supranational and fund units: XBA, XBB, XBC, and XBD (European bond market units), XDR (IMF special drawing rights), XSU (Sucre), and XUA (ADB unit of account).
  • Special-purpose codes: XTS (reserved for testing) and XXX (no currency).

For schema details, see the Storefront GraphQL API reference:

• currency field on the site query
• currencies field on the site query

Fixed deleting and renaming legacy Image Manager images with uppercase letters or underscores in the filename

Deleting or renaming an Image Manager image uploaded before filenames were slugified, such as Home_Header_5.jpg, silently failed. The image stayed in the Image Manager with no error shown to the merchant.

• Legacy filenames are accepted again: delete and rename now validate the filename directly against path traversal, hidden files, and non-image extensions, instead of rejecting any name containing uppercase letters or underscores.
• Errors reach the browser: failed delete and rename requests now return their error message through the response instead of a body the browser couldn’t parse.

For details, see Image Manager.

Product enrichment supports image-based enrichment

Product enrichment can now use supported product images when its model provider cannot access image URLs. The service loads images before requests to the provider.

Merchants do not need to change their catalogs. For details about Catalog Enrichment, see What is Catalog Enrichment?.

Relative bulk pricing tier discounts now convert to the selected currency

Fixes a bug where the Storefront GraphQL API returned an unconverted relative bulk pricing tier discount amount when a shopper’s selected currency isn’t one of the store’s transactional currencies.

• Correct discount amounts — the discount amount on a relative (price-type) bulk pricing tier now applies the store’s exchange rate for the selected currency, matching every other field on Prices, instead of returning the amount as entered in the store’s default currency.

For details, see the Storefront GraphQL API reference.

Update an order reference corrections

Thanks to user feedback, the Update an order reference now matches the live behavior of the v2 Orders API.

• Read-only fields removed from the request schema. external_id and external_merchant_id are no longer listed as writable. Sending either returns a 400 error. items_total, order_is_digital, and tax_provider_id are now marked read-only because the API ignores them in a PUT request.
• is_deleted added to the request schema. Set it to true to archive an order or false to restore one.
• quantity_backordered added to the product schema. The field was documented in the backorders guide but missing from the request reference. It requires quantity in the same product entry.
• Product removal example corrected. The “Removing a product from an order” example now sets quantity to 0, matching the description. The line item stays on the order with a quantity of 0 and no longer counts toward the order totals.
• Product option fields corrected. The remove-product schema now lists id and value for product_options, matching the other product schemas and the examples.
• Fee examples corrected. Fixed the misspelled cost_ex_tax key in the fee request and response examples, and clarified that display_name_merchant is shown to merchants in the control panel.
• 404 response documented. Updating an order that does not exist returns 404.
• include and consignment_structure query parameters documented. The PUT response supports the same include=consignments, consignments.line_items, and fees expansions as Get an order.
• order_source description consolidated. The allowed values now appear in one place in both the request and response schemas.
• Description rewritten. The endpoint description now explains PATCH-like behavior for products and shipping addresses, PUT semantics for fees, archiving with is_deleted, and which fields are read-only.

For details, see Update an order.

“Vault instruments for all card payments” with Braintree is now generally available

The Vault instruments with Braintree for all card payments setting in Control Panel payment provider settings no longer shows a Beta badge — the feature is now generally available.

• Beta badge removed — the setting that stores a provider token for every card used to place an order, including guest checkouts, no longer displays a Beta label.
• No behavior change — the setting’s functionality, description, and confirmation step are unchanged.

For details, see the Stored Instruments API guide.

View web page creation and modification dates

Merchants can now see when a web page was created and last modified in the control panel, making it easier to investigate unexpected store content changes.

• Page dates — View creation and last modification dates in the Web Pages list and page editor.
• Existing pages — Pages created before date tracking was enabled show an unavailable date instead of an estimated date.

For details, see the Pages overview.