BigCommerce Storefront

The BigCommerce Storefront connector runs GraphQL against your store's Storefront API: products, search, categories, carts, checkout, customer profile, wishlists, and site settings. Every action, with its default query, variables, and response fields, is listed in the action reference.

Connecting

Connect using your store's domain and a Storefront API token. Create the token under Channel Manager → Storefronts → your channel → Storefront API Token.

• Store Domain — your store domain without https:// (e.g. store-abc123.mybigcommerce.com).
• Storefront API Token — the Storefront API bearer token for that channel.

Every action posts to https://{storeDomain}/graphql with Authorization: Bearer <token>. Storefront: Get Customer, Storefront: Get Wishlist, and Storefront: Execute Custom GraphQL accept an optional Customer JWT. When set, it replaces the connection's token as the bearer, so the query runs as that authenticated customer instead of the anonymous storefront.

Your first call

1. Add a BigCommerce Storefront step and choose Storefront: Get Site Info. Name it "Get Site Info" so its reference is getSiteInfo.
2. Leave the default query as is.
3. Read the store name in a later step with {{getSiteInfo.response.data.site.settings.storeName}}.

The editable query and variables pattern

Almost every action exposes two fields:

• GraphQL Query (or GraphQL Mutation) — the operation sent to BigCommerce. Each action ships a useful default, but the field is fully editable: add or remove fields, change arguments, or replace the operation with anything the Storefront GraphQL schema supports. Left blank, the action falls back to its default.
• Variables — a JSON string of GraphQL variables (e.g. {"first": 20}). It is parsed with JSON.parse, so it must be valid JSON.

So any action is an entry point into the same Storefront schema: use it as is, or rewrite the query.

Exceptions:

• Storefront: Get Site Info and Storefront: Get Customer expose only GraphQL Query; their default queries take no variables.
• Storefront: Execute Custom GraphQL has no default query or variables. The query is required and variables are optional ({} is sent if omitted). Use it for anything the other actions do not cover.
• Storefront: Customer Login does not use GraphQL at all (see below).

Reading the response

Responses are one level shallower than the Admin GraphQL connector. The Storefront client unwraps GraphQL's own { data, errors } envelope, so queried fields sit directly under response.data:

• {{<stepReference>.response.status}}, .response.statusText, .response.headers.<header-name> — the HTTP result.
• {{<stepReference>.response.data.<field path>}} — the query's top-level field (site, cart, customer) directly under data, with no extra .data.data.

For example, a step named "Get Product" (reference getProduct) reads {{getProduct.response.data.site.product.name}}.

Return full GraphQL response

Every query/mutation action has Return full GraphQL response (off by default). When on, the step returns BigCommerce's whole { data, errors } body and status unchanged. Read fields at {{<stepReference>.response.data.data.<field path>}}, and GraphQL errors arrive in response.data.errors instead of failing the step. Use it when the output goes straight back to a GraphQL client, such as the last step of a gateway route.

Error handling

• GraphQL errors. If BigCommerce's response contains an errors array (a bad field name, an invalid entity ID), the client throws and the action turns it into a synthetic result: {{<stepReference>.response.status}} becomes 500, and {{<stepReference>.response.data.errors.0.message}} holds one string of the form "BigCommerce Storefront GraphQL errors: [...]", where [...] is the JSON-stringified array. It is not a structured array of error objects as in the Admin GraphQL connector. To branch on a GraphQL failure, check status = 500 and parse the embedded JSON if you need detail.
• HTTP errors from BigCommerce itself (bad or expired token gives 401, rate limiting gives 429) are returned as is: response.status is the real code and response.data is BigCommerce's error body.
• Connection failures (DNS, network) come back as a synthetic 503.
• Mutation-level errors are different from top-level errors. Cart mutations return an errors list inside the mutation payload (e.g. {{<stepReference>.response.data.cart.createCart.errors}} for a bad productEntityId), separate from response.data.errors.

Pagination and filtering

• Lists use GraphQL cursors. Request pageInfo { hasNextPage endCursor } and pass endCursor back as the after variable for the next page. after is accepted by the List Products and Search Products queries even though it is not in the default variables.
• Site-level products (Storefront: List Products) accepts only pagination arguments in BigCommerce's real schema, with no filters or sort. For filtering, sorting, or full-text search use Storefront: Search Products (filters.searchTerm, plus optional categoryEntityId, brandEntityIds, price.{minPrice,maxPrice}, and sort such as RELEVANCE). For one category's products use Storefront: Get Category.
• Search Products also returns filters facets (category, brand, price) tagged with their concrete types, for building a filter UI.

Quirks and exceptions

• Product lookup by path. Storefront: Get Product's default query uses site.product(entityId: ...). Looking up by storefront path is a structurally different query against site.route(path: $path) { node { ... on Product { ... } } }. Replace the query text and set variables to {"path": "/running-shoes/"}; you cannot pass a path into the existing $entityId variable.
• Cart and checkout share one ID. The cart's entityId from Create Cart is what Get Cart, Add / Update / Delete Cart Item, Apply Coupon, and Get Checkout take (as entityId or cartEntityId). A checkout is keyed by the same ID as its cart. Update and Delete Cart Item also need a lineItemEntityId, found at lineItems.physicalItems.<n>.entityId in a Get Cart or Add Cart Items result.
• Deleting the last cart item may return cart: null from Delete Cart Item.
• Coupon errors surface as InvalidCouponCodeError or CouponCodeAlreadyAppliedError in the errors list of Apply Coupon.
• Customer-scoped queries need a Customer JWT. customer resolves to whichever customer the bearer token belongs to, so without a JWT Get Customer typically resolves to null. Get Wishlist also needs it; restrict to one wishlist with {"filters": {"entityIds": [123]}}.
• Storefront: Customer Login is not a GraphQL call. It posts email and password to your store's /login.php?action=check_login to verify the credentials. As implemented, it does not return the token / customer_id its output schema declares. On success it returns a fixed acknowledgement, { "success": true, "message": "Customer login initiated. Use customer JWT flow for API operations." }. That result is not tagged as an HTTP result, so it sits on the step output rather than under response: read {{<stepReference>.data.success}} and {{<stepReference>.data.message}}. It confirms the credentials but does not give you a usable customer JWT. To call Get Customer, Get Wishlist, or Execute Custom GraphQL as a customer, obtain a JWT through BigCommerce's own customer JWT flow outside this connector and pass it as Customer JWT. Invalid credentials surface as an HTTP-level error from login.php.

Common tasks

Build a cart and check totals

1. Storefront: Create Cart with variables {"input": {"lineItems": [{"quantity": 1, "productEntityId": 123, "variantEntityId": 456}], "currencyCode": "USD", "locale": "en"}}. Name the step "Create Cart".
2. Storefront: Apply Coupon with {"input": {"cartEntityId": "{{createCart.response.data.cart.createCart.cart.entityId}}", "data": {"couponCode": "SUMMER10"}}}.
3. Storefront: Get Checkout with {"entityId": "{{createCart.response.data.cart.createCart.cart.entityId}}"}, then read {{getCheckout.response.data.site.checkout.grandTotal.value}}.

Show a category page

1. Storefront: Get Category with {"entityId": 12, "productsFirst": 20}.
2. Read {{getCategory.response.data.site.category.products.edges}} and loop over it. Use pageInfo.endCursor for the next page.

Run a query no action covers

1. Choose Storefront: Execute Custom GraphQL and paste your query.
2. Read the result under {{<stepReference>.response.data...}}, with the top-level field directly under data.