younifyd
Menu

Connectors

BigCommerce Storefront

Run and edit GraphQL queries/mutations against BigCommerce's Storefront API for products, cart, checkout, and customer accounts — read data with {{<stepReference>.response.data...}} template syntax.

On this page
AuthenticationThe editable query/variables patternReading the response and GraphQL errorsStorefront: List ProductsQueryVariablesResponseStorefront: Get ProductQueryVariablesResponseStorefront: Search ProductsQueryVariablesResponseStorefront: Get CategoryQueryVariablesResponseStorefront: Create CartQueryVariablesResponseStorefront: Get CartQueryVariablesResponseStorefront: Add Cart ItemsQueryVariablesResponseStorefront: Update Cart ItemQueryVariablesResponseStorefront: Delete Cart ItemQueryVariablesResponseStorefront: Apply CouponQueryVariablesResponseStorefront: Get CheckoutQueryVariablesResponseStorefront: Customer LoginConfiguring itResponseStorefront: Get CustomerQueryVariablesResponseStorefront: Get WishlistQueryVariablesResponseStorefront: Get Site InfoQueryVariablesResponseStorefront: Execute Custom GraphQLQueryVariablesResponseStep NameStep ReferenceExecution SettingsCachingLocking

Authentication

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

  • Store Domain — your BigCommerce 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>. A handful of actions (Storefront: Get Customer, Storefront: Get Wishlist, Storefront: Execute Custom GraphQL) accept an optional Customer JWT field — when set, it's used as the bearer token instead of the connection's Storefront token, so the query runs as that authenticated customer rather than as the anonymous storefront.

The editable query/variables pattern

Unlike a typical fixed-input connector action, almost every action on this connector exposes just two input fields:

  • GraphQL Query (or GraphQL Mutation) — the actual query/mutation text sent to BigCommerce's Storefront GraphQL API. Each action ships with a default query that already does something useful, but this field is fully editable — add or remove fields, change arguments, or replace the operation entirely with any other query or mutation the Storefront GraphQL schema supports. If you leave it blank, the action falls back to its default query.
  • Variables — a JSON string of GraphQL query variables (e.g. {"first": 20}). Also editable with its own default; parsed with JSON.parse before being sent, so it must be valid JSON.

This makes the connector a general-purpose escape hatch into BigCommerce's Storefront GraphQL schema: use an action as-is for its default behavior, or rewrite the query to ask for different fields or perform a different operation in the same part of the schema.

Three actions deviate from the two-field pattern, worth calling out up front:

  • Storefront: Get Site Info and Storefront: Get Customer only expose GraphQL Query — their default queries take no $-prefixed arguments, so there's no Variables field for them.
  • Storefront: Execute Custom GraphQL ships with no default query or variables at all — both fields start empty (query is required), since it's the connector's raw escape hatch rather than a pre-built lookup.
  • Storefront: Customer Login doesn't use this pattern at all — see its own section below.

Reading the response and GraphQL errors

Every query/mutation action shares the same response envelope, readable from later steps via its Step Reference — written here as <stepReference>. This is one level shallower than BigCommerce's Admin GraphQL connector: the Storefront client (runStorefrontQuery) already unwraps GraphQL's own { data: {...}, errors: [...] } envelope before returning, so you read queried fields straight off response.data — there is no second .data to unwrap.

  • {{<stepReference>.response.status}} / {{<stepReference>.response.statusText}} — the HTTP status of the call. Usually 200 for a clean success.
  • {{<stepReference>.response.headers.<header-name>}} — a response header.
  • {{<stepReference>.response.data.<field path>}} — the queried data, with the query's own top-level field (site, cart, customer, ...) directly under data — no extra .data.data.

For example, a step named "Get Site Info" (reference getSiteInfo) using the default query — read the store name with {{getSiteInfo.response.data.site.settings.storeName}}.

GraphQL-level errors work differently here than in the Admin GraphQL connector. If BigCommerce's GraphQL response body includes an errors array (e.g. a bad field name, an invalid entity ID), the Storefront client throws before returning; the action's own error handling catches that and turns it into a synthetic HTTP result instead of failing the step outright:

  • {{<stepReference>.response.status}} becomes 500.
  • {{<stepReference>.response.data.errors.0.message}} holds a single message string of the form "BigCommerce Storefront GraphQL errors: [...]", where the [...] is the JSON-stringified array of the actual GraphQL errors — not a structured array of individual error objects the way the Admin GraphQL connector returns them.

So to branch on a GraphQL failure from this connector, check {{<stepReference>.response.status}} = 500 and, if you need the underlying detail, parse the JSON embedded in {{<stepReference>.response.data.errors.0.message}}.

A real HTTP-level failure from BigCommerce itself (bad/expired token → 401, rate limiting → 429, etc.) is returned as-is: {{<stepReference>.response.status}} reflects that real status code, and {{<stepReference>.response.data}} is whatever error body BigCommerce sent — not the GraphQL error shape above. A connection failure (DNS/network) comes back as a synthetic 503.

Product & Catalog actions

Storefront: List Products

Page through products via the BigCommerce Storefront GraphQL API — the query is editable, so you decide exactly what comes back.

Query

query BCListProducts($first: Int!, $after: String) {
  site {
    products(first: $first, after: $after) {
      pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
      edges {
        cursor
        node {
          entityId id name sku path description
          defaultImage { url(width: 500) altText }
          prices {
            price { value currencyCode }
            salePrice { value currencyCode }
            priceRange { min { value currencyCode } max { value currencyCode } }
          }
          availabilityV2 { status description }
          categories { edges { node { entityId name path } } }
          brand { entityId name }
        }
      }
    }
  }
}

Variables

{
  "first": 20
}
  • first — page size; how many products to return in this page.
  • after (not in the default, but accepted by the query) — the pagination cursor from a previous page's pageInfo.endCursor, to fetch the next page.

Site-level products only accepts pagination arguments in BigCommerce's real schema — no filters or sort. For filtering, sorting, or full-text search, use Storefront: Search Products instead; for a single category's products, use Storefront: Get Category.

Response

  • {{<stepReference>.response.data.site.products.pageInfo.hasNextPage}} / {{<stepReference>.response.data.site.products.pageInfo.endCursor}}
  • {{<stepReference>.response.data.site.products.edges}} — an array; each entry's node has entityId, name, sku, path, description, defaultImage, prices, availabilityV2, categories, brand. E.g. the first product's name: {{<stepReference>.response.data.site.products.edges.0.node.name}}.

Storefront: Get Product

Retrieve a single product by entity ID (or path, with an edited query) from BigCommerce Storefront — the query is editable, so you decide exactly what comes back.

Query

query BCGetProductById($entityId: Int!) {
  site {
    product(entityId: $entityId) {
      entityId id name sku description
      defaultImage { url(width: 800) altText }
      prices {
        price { value currencyCode }
        salePrice { value currencyCode }
      }
      availabilityV2 { status description }
      variants(first: 100) {
        edges {
          node {
            entityId sku
            prices { price { value currencyCode } }
            inventory { isInStock }
            options { edges { node { entityId displayName values { edges { node { entityId label } } } } } }
          }
        }
      }
      categories { edges { node { entityId name } } }
      brand { entityId name }
    }
  }
}

Variables

{
  "entityId": 123
}
  • entityId — the BigCommerce product entity ID to look up.

The default query looks a product up by entityId via site.product(entityId: ...). Looking a product up by its storefront path instead is not a variant of this same query — it's a structurally different query against a different root field, site.route(path: $path) { node { ... on Product { ... } } }. To switch lookup modes, replace the query text itself with a site.route-based query and set variables to {"path": "/running-shoes/"}, rather than trying to pass a path into the existing $entityId variable.

Response

  • {{<stepReference>.response.data.site.product.entityId}} / .name / .sku / .description
  • {{<stepReference>.response.data.site.product.prices.price.value}}
  • {{<stepReference>.response.data.site.product.variants.edges.0.node.inventory.isInStock}}

Storefront: Search Products

Full-text search across BigCommerce storefront products with faceted filters — the query is editable, so you decide exactly what comes back.

Query

query BCSearchProducts($filters: SearchProductsFiltersInput!, $sort: SearchProductsSortInput, $first: Int!, $after: String) {
  site {
    search {
      searchProducts(filters: $filters, sort: $sort) {
        products(first: $first, after: $after) {
          pageInfo { hasNextPage endCursor }
          edges {
            cursor
            node {
              entityId name sku path
              defaultImage { url(width: 400) altText }
              prices { price { value currencyCode } salePrice { value currencyCode } }
              availabilityV2 { status }
              brand { name }
              categories { edges { node { name } } }
            }
          }
        }
        filters {
          edges {
            node {
              name isCollapsedByDefault
              ... on CategorySearchFilter { name displayProductCount categories { edges { node { entityId name productCount isSelected subCategories { edges { node { entityId name } } } } } } }
              ... on BrandSearchFilter { name displayProductCount brands { edges { node { entityId name productCount isSelected } } } }
              ... on PriceSearchFilter { name selected { minPrice maxPrice } }
            }
          }
        }
      }
    }
  }
}

Variables

{
  "filters": { "searchTerm": "blue running shoes" },
  "sort": "RELEVANCE",
  "first": 20
}
  • filters.searchTerm — the free-text search query (required for a real search).
  • filters.categoryEntityId / filters.brandEntityIds / filters.price.{minPrice,maxPrice} — optional facet filters, not in the default but accepted by the query.
  • sort — e.g. RELEVANCE, or another SearchProductsSortInput value.
  • first / after — pagination, same convention as Storefront: List Products.

Response

  • {{<stepReference>.response.data.site.search.searchProducts.products.edges}} — matching products; e.g. {{<stepReference>.response.data.site.search.searchProducts.products.edges.0.node.name}}.
  • {{<stepReference>.response.data.site.search.searchProducts.filters.edges}} — the available facets (category/brand/price) for building a filter UI, each tagged with its concrete type (CategorySearchFilter, BrandSearchFilter, PriceSearchFilter).

Storefront: Get Category

Get a category with its products from BigCommerce Storefront — the query is editable, so you decide exactly what comes back.

Query

query BCGetCategory($entityId: Int!, $productsFirst: Int!) {
  site {
    category(entityId: $entityId) {
      entityId name path description
      image { url(width: 800) altText }
      seo { pageTitle metaDescription }
      products(first: $productsFirst) {
        pageInfo { hasNextPage endCursor }
        edges {
          node {
            entityId name sku path
            defaultImage { url(width: 400) altText }
            prices { price { value currencyCode } salePrice { value currencyCode } }
            availabilityV2 { status }
          }
        }
      }
    }
  }
}

Variables

{
  "entityId": 12,
  "productsFirst": 20
}
  • entityId — the BigCommerce category entity ID.
  • productsFirst — how many of the category's products to return in this page.

Response

  • {{<stepReference>.response.data.site.category.name}} / .description / .seo.pageTitle
  • {{<stepReference>.response.data.site.category.products.edges}} — products in the category; e.g. {{<stepReference>.response.data.site.category.products.edges.0.node.path}}.

Cart actions

Storefront: Create Cart

Create a new shopping cart in BigCommerce Storefront via GraphQL — the mutation is editable, so you decide exactly what comes back.

Query

mutation BCCreateCart($input: CreateCartInput!) {
  cart {
    createCart(input: $input) {
      cart {
        entityId
        lineItems {
          physicalItems {
            entityId name quantity
            imageUrl
            originalPrice { value currencyCode }
            extendedSalePrice { value currencyCode }
            selectedOptions { name value }
          }
          digitalItems { entityId name quantity originalPrice { value currencyCode } }
        }
        amount { value currencyCode }
        discountedAmount { value currencyCode }
        discounts { entityId discountedAmount { value currencyCode } }
      }
      errors {
        ... on CartItemProductNotFoundError { message }
        ... on CartItemVariantNotFoundError { message }
      }
    }
  }
}

Variables

{
  "input": {
    "lineItems": [
      { "quantity": 1, "productEntityId": 123, "variantEntityId": 456 }
    ],
    "currencyCode": "USD",
    "locale": "en"
  }
}
  • input.lineItems — array of items to seed the cart with; each entry needs quantity, productEntityId, and (for variant products) variantEntityId.
  • input.currencyCode — the cart's currency.
  • input.locale — the cart's locale.

Response

  • {{<stepReference>.response.data.cart.createCart.cart.entityId}} — the new cart's ID. Later cart/checkout actions (Storefront: Get Cart, Add/Update/Delete Cart Item, Apply Coupon, Get Checkout) all take this as their entityId/cartEntityId variable, so a step named "Create Cart" (reference createCart) feeds {{createCart.response.data.cart.createCart.cart.entityId}} into those steps' Variables.
  • {{<stepReference>.response.data.cart.createCart.cart.amount.value}}
  • {{<stepReference>.response.data.cart.createCart.errors}} — mutation-level errors (e.g. a bad productEntityId), distinct from top-level {{<stepReference>.response.data.errors}}.

Storefront: Get Cart

Retrieve current cart state from BigCommerce Storefront — the query is editable, so you decide exactly what comes back.

Query

query BCGetCart($entityId: String!) {
  site {
    cart(entityId: $entityId) {
      entityId
      lineItems {
        physicalItems {
          entityId name quantity sku
          imageUrl
          originalPrice { value currencyCode }
          salePrice { value currencyCode }
          extendedSalePrice { value currencyCode }
          selectedOptions { name value }
        }
        digitalItems { entityId name quantity originalPrice { value currencyCode } }
        giftCertificates { entityId name amount { value currencyCode } }
      }
      amount { value currencyCode }
      discountedAmount { value currencyCode }
      discounts { entityId discountedAmount { value currencyCode } }
      coupons { entityId code discountedAmount { value currencyCode } }
      currencyCode
      isTaxIncluded
      locale
    }
  }
}

Variables

{
  "entityId": "b20d7fba-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
  • entityId — the cart's ID, typically {{<stepReference>.response.data.cart.createCart.cart.entityId}} from a prior Storefront: Create Cart step.

Response

  • {{<stepReference>.response.data.site.cart.lineItems.physicalItems}} — array of physical line items; e.g. {{<stepReference>.response.data.site.cart.lineItems.physicalItems.0.quantity}}.
  • {{<stepReference>.response.data.site.cart.amount.value}} / {{<stepReference>.response.data.site.cart.discountedAmount.value}}
  • {{<stepReference>.response.data.site.cart.coupons}} — applied coupons, if any.

Storefront: Add Cart Items

Add one or more products to an existing BigCommerce cart via the Storefront GraphQL API — the mutation is editable, so you decide exactly what comes back.

Query

mutation BCAddCartItems($input: AddCartLineItemsInput!) {
  cart {
    addCartLineItems(input: $input) {
      cart {
        entityId
        lineItems {
          physicalItems { entityId name quantity extendedSalePrice { value currencyCode } }
        }
        amount { value currencyCode }
        discountedAmount { value currencyCode }
      }
      errors {
        ... on CartItemProductNotFoundError { message }
        ... on CartItemVariantNotFoundError { message }
      }
    }
  }
}

Variables

{
  "input": {
    "cartEntityId": "b20d7fba-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "data": {
      "lineItems": [
        { "quantity": 1, "productEntityId": 123, "variantEntityId": 456 }
      ]
    }
  }
}
  • input.cartEntityId — the existing cart's ID (from Storefront: Create Cart).
  • input.data.lineItems — items to add, same shape as Storefront: Create Cart's lineItems.

Response

  • {{<stepReference>.response.data.cart.addCartLineItems.cart.lineItems.physicalItems}} — the cart's line items after adding.
  • {{<stepReference>.response.data.cart.addCartLineItems.errors}} — mutation-level errors, e.g. an unknown variantEntityId.

Storefront: Update Cart Item

Update the quantity of an item in a BigCommerce cart via the Storefront GraphQL API — the mutation is editable, so you decide exactly what comes back.

Query

mutation BCUpdateCartItem($input: UpdateCartLineItemInput!) {
  cart {
    updateCartLineItem(input: $input) {
      cart {
        entityId
        lineItems {
          physicalItems { entityId name quantity extendedSalePrice { value currencyCode } }
        }
        amount { value currencyCode }
        discountedAmount { value currencyCode }
      }
      errors {
        ... on CartItemProductNotFoundError { message }
      }
    }
  }
}

Variables

{
  "input": {
    "cartEntityId": "b20d7fba-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "lineItemEntityId": "66a1b2c3d4e5f60007a1b2c3",
    "data": {
      "lineItem": {
        "quantity": 2,
        "productEntityId": 123,
        "variantEntityId": 456
      }
    }
  }
}
  • input.cartEntityId — the cart's ID.
  • input.lineItemEntityId — the line item to update, e.g. from a prior Storefront: Get Cart or Storefront: Add Cart Items step's lineItems.physicalItems.<n>.entityId.
  • input.data.lineItem — the new quantity, plus productEntityId/variantEntityId for the item.

Response

  • {{<stepReference>.response.data.cart.updateCartLineItem.cart.lineItems.physicalItems}} — the cart's line items after updating.
  • {{<stepReference>.response.data.cart.updateCartLineItem.errors}}

Storefront: Delete Cart Item

Remove a line item from a BigCommerce cart via the Storefront GraphQL API — the mutation is editable, so you decide exactly what comes back.

Query

mutation BCDeleteCartItem($input: DeleteCartLineItemInput!) {
  cart {
    deleteCartLineItem(input: $input) {
      cart {
        entityId
        lineItems {
          physicalItems { entityId name quantity extendedSalePrice { value currencyCode } }
        }
        amount { value currencyCode }
        discountedAmount { value currencyCode }
      }
      errors { ... on CartLineItemNotFoundError { message } }
    }
  }
}

Variables

{
  "input": {
    "cartEntityId": "b20d7fba-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "lineItemEntityId": "66a1b2c3d4e5f60007a1b2c3"
  }
}
  • input.cartEntityId — the cart's ID.
  • input.lineItemEntityId — the line item to remove.

Response

  • {{<stepReference>.response.data.cart.deleteCartLineItem.cart}} — the cart after removal; if it was the last item, BigCommerce may return cart: null.
  • {{<stepReference>.response.data.cart.deleteCartLineItem.errors}} — e.g. a lineItemEntityId that no longer exists.

Storefront: Apply Coupon

Apply a coupon code to a BigCommerce cart via the Storefront GraphQL API — the mutation is editable, so you decide exactly what comes back.

Query

mutation BCApplyCouponCode($input: ApplyCouponCodeInput!) {
  cart {
    applyCouponCode(input: $input) {
      cart {
        entityId
        coupons { entityId code discountedAmount { value currencyCode } }
        amount { value currencyCode }
        discountedAmount { value currencyCode }
      }
      errors {
        ... on CouponCodeAlreadyAppliedError { message }
        ... on InvalidCouponCodeError { message }
      }
    }
  }
}

Variables

{
  "input": {
    "cartEntityId": "b20d7fba-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "data": { "couponCode": "SUMMER10" }
  }
}
  • input.cartEntityId — the cart's ID.
  • input.data.couponCode — the coupon code to apply.

Response

  • {{<stepReference>.response.data.cart.applyCouponCode.cart.coupons}} — applied coupons; e.g. {{<stepReference>.response.data.cart.applyCouponCode.cart.coupons.0.discountedAmount.value}}.
  • {{<stepReference>.response.data.cart.applyCouponCode.errors}} — e.g. an invalid or already-applied code (InvalidCouponCodeError, CouponCodeAlreadyAppliedError).

Storefront: Get Checkout

Get checkout details including tax, shipping, and grand total for a BigCommerce cart — the query is editable, so you decide exactly what comes back.

Query

query BCGetCheckout($entityId: String!) {
  site {
    checkout(entityId: $entityId) {
      entityId
      shippingCostTotal { value currencyCode }
      handlingCostTotal { value currencyCode }
      taxTotal { value currencyCode }
      subtotal { value currencyCode }
      grandTotal { value currencyCode }
      giftCertificates { code balance { value currencyCode } }
      promotions { bannerText }
      cart {
        entityId
        lineItems {
          physicalItems { entityId name quantity extendedSalePrice { value currencyCode } }
        }
        amount { value currencyCode }
        discountedAmount { value currencyCode }
      }
    }
  }
}

Variables

{
  "entityId": "b20d7fba-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
  • entityId — the cart's ID; a checkout in BigCommerce's storefront schema is keyed by the same ID as its cart, so this is the same value used for Storefront: Get Cart.

Response

  • {{<stepReference>.response.data.site.checkout.grandTotal.value}} / .taxTotal.value / .shippingCostTotal.value
  • {{<stepReference>.response.data.site.checkout.cart.lineItems.physicalItems}}

Customer actions

Storefront: Customer Login

Authenticate a customer via BigCommerce Storefront and get a customer JWT for subsequent requests.

This action does not follow the query/variables pattern — it doesn't call the Storefront GraphQL API at all. It posts email/password straight to your store's /login.php?action=check_login endpoint to verify the credentials.

Configuring it

  • Email (required) — the customer's email address.
  • Password (required) — the customer's password.

Response

As currently implemented, this action does not return the token/customer_id fields its output schema declares. If BigCommerce accepts the credentials (a non-error HTTP response), it returns a fixed acknowledgement object:

{ "success": true, "message": "Customer login initiated. Use customer JWT flow for API operations." }

Because this result isn't tagged as an HTTP result the way the GraphQL actions are, it's wrapped verbatim on the step output rather than under response... — read it as {{<stepReference>.data.success}} / {{<stepReference>.data.message}}. It confirms the credentials are valid but does not hand back a usable Storefront customer JWT. To call Storefront: Get Customer, Storefront: Get Wishlist, or Storefront: Execute Custom GraphQL as an authenticated customer, obtain a customer JWT via BigCommerce's own customer JWT issuance flow outside this connector and pass it into those actions' Customer JWT field. Invalid credentials surface as an HTTP-level error from login.php (see "Reading the response and GraphQL errors" above).

Storefront: Get Customer

Get the currently authenticated customer's profile and addresses from BigCommerce Storefront — the query is editable, so you decide exactly what comes back.

Query

query BCGetCustomer {
  customer {
    entityId
    firstName
    lastName
    email
    phone
    company
    customerGroupId
    notes
    taxExemptCategory
    addressCount
    attributeCount
    addresses {
      edges {
        node {
          entityId
          firstName lastName
          address1 address2
          city stateOrProvince
          postalCode
          country countryCode
          phone
          isDefaultBilling
          isDefaultShipping
        }
      }
    }
  }
}

Variables

This query takes no variables, so there's no Variables field for it. It does have a Customer JWT field — a customer-scoped JWT is required, since customer resolves to whichever customer the bearer token belongs to; without one, this typically resolves to null.

Response

  • {{<stepReference>.response.data.customer.email}} / .firstName / .lastName
  • {{<stepReference>.response.data.customer.addresses.edges}} — e.g. {{<stepReference>.response.data.customer.addresses.edges.0.node.city}}.

Storefront: Get Wishlist

Get customer wishlists from BigCommerce Storefront — the query is editable, so you decide exactly what comes back.

Query

query BCGetWishlists($filters: WishlistFiltersInput) {
  customer {
    wishlists(filters: $filters) {
      edges {
        node {
          entityId name isPublic
          token
          items {
            edges {
              node {
                entityId
                product {
                  entityId name sku path
                  defaultImage { url(width: 400) altText }
                  prices { price { value currencyCode } }
                }
              }
            }
          }
        }
      }
    }
  }
}

Variables

{}
  • filters.entityIds (not in the default) — set to {"filters": {"entityIds": [123]}} to restrict to one wishlist by ID.

Also has a Customer JWT field, required to resolve customer to the right shopper.

Response

  • {{<stepReference>.response.data.customer.wishlists.edges}} — e.g. {{<stepReference>.response.data.customer.wishlists.edges.0.node.name}}.
  • {{<stepReference>.response.data.customer.wishlists.edges.0.node.items.edges.0.node.product.name}} — a wishlisted product's name.

Site info & advanced

Storefront: Get Site Info

Get BigCommerce store settings, currencies, category tree, and brand list — the query is editable, so you decide exactly what comes back.

Query

query BCGetSiteInfo {
  site {
    settings {
      storeName
      storeHash
      status
      logo { image { url(width: 300) } }
      contact { address city country countryCode phone email }
      url { vanityUrl cdnUrl }
      socialMediaLinks { name url }
      tax { plp { label rate } }
    }
    currency { code name }
    currencies { edges { node { entityId code name isDefault } } }
    categoryTree {
      entityId name path
      children {
        entityId name path
        children { entityId name path }
      }
    }
    brands { edges { node { entityId name path } } }
  }
}

Variables

This query takes no variables, so there's no Variables field for it — edit the query text directly to add or remove fields.

Response

  • {{<stepReference>.response.data.site.settings.storeName}} / .contact.email
  • {{<stepReference>.response.data.site.currency.code}}
  • {{<stepReference>.response.data.site.categoryTree}} — nested category tree; e.g. {{<stepReference>.response.data.site.categoryTree.0.children.0.name}} for a second-level category name.
  • {{<stepReference>.response.data.site.brands.edges}}

Storefront: Execute Custom GraphQL

Run any custom GraphQL query or mutation against the BigCommerce Storefront API.

This is the generic escape hatch of the sixteen actions — it ships with no default query or variables (the GraphQL Query field is required with no default; Variables is optional and empty by default). It also accepts a Customer JWT field to run as an authenticated customer.

Query

There's no default — paste any Storefront GraphQL query or mutation not covered by the other fifteen actions, e.g.:

query BCGetStoreCurrency {
  site {
    currency { code name }
  }
}

Variables

Optional. A JSON object of query variables matching whatever your query declares. If omitted, an empty object {} is sent.

Response

Depends entirely on the query you provide — as with every other action here, the top-level field(s) land directly under {{<stepReference>.response.data...}} (no extra .data.data). Using the example above: {{<stepReference>.response.data.site.currency.code}}.

Also applies here

Step Name

What it's for

Every step in a workflow gets a name — either one you set or a default based on the connector and action (e.g. "Get Order Details", "Send Welcome Email"). It's shown throughout the UI and in your execution history, and it's also the source for the step's Reference — a camelCase identifier auto-generated from the name (e.g. "Get Order Details" → getOrderDetails) — which is what you actually use in {{...}} expressions to read this step's output from later steps. See Step Reference.

Rules

  • Must be at least 2 characters, and 50 characters or fewer.
  • Must be unique within the workflow — reusing a name that's already taken will be rejected, with a suggested alternative (e.g. "Get Order Details 2").
  • Can't be empty.

Tips

  • Prefer a descriptive, human-readable name over a generic one — "Get Order Details" is easier to work with later than "HTTP Request 2", especially once a workflow has a dozen steps.
  • Renaming a step updates every reference to it elsewhere in the workflow automatically.

Step Reference

Syntax

Any input field can reference earlier data using {{expression}}. The expression is evaluated as JSONata — so simple dot-paths and more advanced queries (filters, functions) both work.

Referencing a step's output

Use the step's Reference — a camelCase identifier auto-generated from its Name (e.g. "Get Order Details" → getOrderDetails), shown read-only wherever the step's fields are configured — followed by the field path. Elsewhere in these docs this general pattern is written as {{<stepReference>.field.path}}:

{{getOrderDetails.response.data.id}}
{{getOrderDetails.response.status}}

The raw display name won't work here even though it's what you see in the UI — {{Get Order Details.response.data.id}} isn't valid, since a bare name containing spaces isn't a single JSONata identifier. Always use the camelCase Reference.

You can also reference steps by position instead of by reference:

{{steps[0].response.data.id}}

Referencing trigger data

{{trigger.headers.authorization}}
{{trigger.body.customerId}}
{{trigger.query.page}}
{{trigger.params.orderId}}
{{trigger.method}}
{{trigger.path}}

Referencing workflow variables

{{variables.myVariable}}

See Variables for the full list of variable types and more examples, including connection-type variables.

Referencing runtime variables

A separate, mutable namespace written by the Variable connector while a run is in progress — not the same as the workflow-level variables above:

{{runtimeVariables.myVariable}}

Notes

  • If an expression can't be resolved (a typo in a step name, a field that doesn't exist), it resolves to an empty string rather than failing the workflow — check your execution history if a value comes through blank.
  • Object values are automatically JSON-stringified when interpolated into a string field.

Execution Settings

Fire-and-forget

When enabled, the workflow doesn't wait for this step to complete before moving to the next one. Use it for steps whose result nothing downstream depends on — logging, analytics, notifications — so they don't add latency to the steps that matter.

Continue on error

When enabled, a failure in this step doesn't stop the workflow — execution continues to the next step. The failure is still recorded in the execution history; this just controls whether it's fatal.

Combine the two for steps that are genuinely optional to the outcome: fire-and-forget so they don't add latency, continue-on-error so a failure in them (e.g. an analytics endpoint being briefly down) doesn't take down an otherwise-successful workflow run.

Caching

What it does

When enabled, a step's result is cached for a configurable TTL (time-to-live, in seconds). If the step runs again with the same effective cache key before the TTL expires, the cached result is returned instead of re-running the step.

Configuring it

  • Enabled — turn caching on or off for this step.
  • TTL — how long (in seconds) a cached result stays valid.
  • Cache key template — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same call". By default this is based on the step's resolved input; a custom template lets you cache more narrowly or broadly than that.

When to use it

Good candidates are steps that call something slow or rate-limited but return the same answer for the same input within a short window — a lookup against a rarely-changing external system, for example. Skip it for steps whose result must always be fresh (anything involving live inventory, pricing, or payment state).

Locking

What it does

When enabled, only one execution of this step (for a given lock key) can run at a time. If a second execution tries to run the same step while a lock is held, it waits until the lock is released or the hold period elapses.

Configuring it

  • Enabled — turn locking on or off for this step.
  • Lock key — an expression (supporting the same {{...}} step reference syntax used elsewhere) that determines what counts as "the same resource". By default the lock is scoped to the step itself; a custom key lets you lock per-customer, per-order, or any other identifier that needs serialized access.
  • Period — how long (in seconds) the lock is held before it's automatically released, in case an execution doesn't complete normally.

When to use it

Use it whenever concurrent executions could race on the same resource — e.g. two workflow runs both trying to update the same order's status at once. A lock key scoped to the order id ensures only one of them proceeds at a time.