BigCommerce Admin GraphQL

Authentication

Connect using the same credentials as the BigCommerce (REST) connector: your store hash and an Admin API access token. Create API credentials under Advanced Settings → API Accounts with the scopes each query or mutation you plan to run requires — if either value is missing, the action fails with an error telling you to look there.

• Store Hash — your BigCommerce store identifier (the 6-character string from your Admin URL).
• API Access Token — the Admin API access token, sent as the X-Auth-Token header.

Every action posts to https://api.bigcommerce.com/stores/{storeHash}/graphql.

The editable query/variables pattern

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

• GraphQL Query (or GraphQL Mutation) — the actual query/mutation text sent to BigCommerce's Admin GraphQL API. Each action ships with a default query that already does something useful, but this field is fully editable — you can add or remove fields, change filters, or replace the operation entirely with any other query or mutation the Admin GraphQL API 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": 10}). 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 Admin GraphQL schema: use an action as-is for its default behavior, or rewrite the query to ask for different fields, add pagination arguments, or perform a completely different operation available in the same part of the schema (e.g. editing "Get Store Settings" to also fetch store { currency }).

Reading the response and GraphQL errors

Every action returns the same envelope shape, readable from later steps via its Step Reference — written here as <stepReference>:

• {{<stepReference>.response.status}} / {{<stepReference>.response.statusText}} — the HTTP status of the call to BigCommerce. This is usually 200 even when the GraphQL query itself has errors — GraphQL reports errors inside the response body, not via HTTP status.
• {{<stepReference>.response.headers.<header-name>}} — a response header.
• {{<stepReference>.response.data.data.<field path>}} — the actual queried data. The first .data unwraps the connector's HTTP envelope; the second .data is GraphQL's own top-level { data: {...}, errors: [...] } convention, so you always see .data.data before the fields your query actually asked for.
• {{<stepReference>.response.data.errors}} — an array of GraphQL errors, if the query or mutation failed at the GraphQL level (e.g. a bad field name, a validation error inside a mutation payload). Check this even when {{<stepReference>.response.status}} is 200.

For example, a step named "Get Store Settings" (reference getStoreSettings) whose query asks for store { name } — read the store name with {{getStoreSettings.response.data.data.store.name}}, and check for query errors with {{getStoreSettings.response.data.errors}}.

Admin GraphQL: Execute Query

Execute any custom GraphQL query or mutation against the BigCommerce Admin GraphQL API.

This is the generic escape hatch of the five actions — it ships with no default query of its own (the query field is required and has no default), only a placeholder shown in the editor, and no default variables either.

Query

There's no server-side default — the input schema's query field is required with this shown only as UI placeholder text:

query GetStoreSettings {
  store {
    storeHash
    name
    primaryDomain { host url }
    status { current }
  }
}

Variables

Optional. A JSON object of query variables matching whatever variables your query declares, e.g. {"first": 10}. If omitted, an empty object {} is sent.

Response

Depends entirely on the query you provide — the top-level field(s) under {{<stepReference>.response.data.data...}} mirror whatever your query selects. Using the placeholder query above, the store hash is at {{<stepReference>.response.data.data.store.storeHash}}.

Example

Since this action has no default, use it to run any Admin GraphQL operation not covered by the other four actions — for example, a metafields or channels query — by pasting the full query into GraphQL Query and its variables into Variables.

Admin GraphQL: Get Store Settings

Retrieve BigCommerce store settings, domain, contact, units, and tax configuration via Admin GraphQL — the query is editable, so you decide exactly what comes back.

Query

query BCGetStoreSettings {
  store {
    storeHash
    name
    primaryDomain { host url }
    languages { edges { node { code isDefault } } }
    metaDomain { host }
    logo { title image { urlOriginal altText } }
    contact { address city country countryCode phone email }
    units { weight { unitName abbreviation } dimension { unitName abbreviation } }
    taxes {
      plp { enabled label rate }
      pdp { enabled label rate }
      shipping { enabled label rate }
    }
  }
}

Variables

This action takes no variables — the query has no $-prefixed arguments, so there's no Variables field for it.

Response

The queried data is under store:

• {{<stepReference>.response.data.data.store.storeHash}}
• {{<stepReference>.response.data.data.store.name}}
• {{<stepReference>.response.data.data.store.primaryDomain.host}}
• {{<stepReference>.response.data.data.store.contact.email}}
• {{<stepReference>.response.data.data.store.taxes.shipping.rate}}

Example

To fetch fewer fields, edit the query directly — e.g. drop taxes and units if you only need name and primaryDomain.

Admin GraphQL: List URL Redirects

List URL redirects configured in BigCommerce via Admin GraphQL — the query is editable, so you decide exactly what comes back.

Query

query BCListRedirects($filter: RedirectsFiltersInput, $first: Int!, $after: String) {
  store {
    redirects(filter: $filter, first: $first, after: $after) {
      pageInfo { hasNextPage endCursor }
      edges {
        node {
          entityId
          fromPath
          to { ... on ManualRedirect { url } ... on ExistingPageRedirect { entityType entityId } }
          statusCode
          siteId
        }
      }
    }
  }
}

Variables

{
  "first": 50,
  "filter": { "siteId": 1 }
}

• first — page size; how many redirects to return in this page.
• filter.siteId — which storefront/site's redirects to list (relevant for multi-storefront stores).
• 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.

Response

• {{<stepReference>.response.data.data.store.redirects.pageInfo.hasNextPage}}
• {{<stepReference>.response.data.data.store.redirects.pageInfo.endCursor}}
• {{<stepReference>.response.data.data.store.redirects.edges}} — an array; each entry's node has entityId, fromPath, to, statusCode, siteId. E.g. the first redirect's target path: {{<stepReference>.response.data.data.store.redirects.edges.0.node.fromPath}}.

Example

To page through a large redirect list, run this action again with Variables set to {"first": 50, "filter": {"siteId": 1}, "after": "<endCursor from the previous page>"}. To list redirects for a different storefront, change filter.siteId.

Admin GraphQL: Create URL Redirect

Create a 301/302 URL redirect in BigCommerce via Admin GraphQL — the mutation is editable, so you decide exactly what comes back.

Query

mutation BCCreateRedirects($input: CreateRedirectsInput!) {
  redirects {
    createRedirects(input: $input) {
      redirects {
        entityId fromPath statusCode
        to { ... on ManualRedirect { url } }
      }
      errors { message }
    }
  }
}

Variables

{
  "input": {
    "siteId": 1,
    "redirects": [
      { "fromPath": "/old-product-page", "to": { "url": "/new-product-page" }, "statusCode": 301 }
    ]
  }
}

• input.siteId — which storefront/site to create the redirect(s) on.
• input.redirects — an array of redirects to create; each entry has fromPath (the old URL path to redirect from), to.url (the destination), and statusCode (301 for permanent, 302 for temporary).

Response

• {{<stepReference>.response.data.data.redirects.createRedirects.redirects}} — the created redirect(s); e.g. {{<stepReference>.response.data.data.redirects.createRedirects.redirects.0.entityId}} for the new redirect's id.
• {{<stepReference>.response.data.data.redirects.createRedirects.errors}} — mutation-level errors (distinct from top-level {{<stepReference>.response.data.errors}}), e.g. a fromPath that already has a redirect.

Example

To create multiple redirects in one call, add more entries to variables.input.redirects:

{
  "input": {
    "siteId": 1,
    "redirects": [
      { "fromPath": "/old-product-page", "to": { "url": "/new-product-page" }, "statusCode": 301 },
      { "fromPath": "/old-category", "to": { "url": "/new-category" }, "statusCode": 301 }
    ]
  }
}

Admin GraphQL: Delete URL Redirect

Delete one or more URL redirects in BigCommerce via Admin GraphQL — the mutation is editable, so you decide exactly what comes back.

Query

mutation BCDeleteRedirects($input: DeleteRedirectsInput!) {
  redirects {
    deleteRedirects(input: $input) {
      deletedRedirectEntityIds
      errors { message }
    }
  }
}

Variables

{
  "input": { "siteId": 1, "entityIds": [1, 2, 3] }
}

• input.siteId — which storefront/site the redirects belong to.
• input.entityIds — the redirect ids to delete (the same entityId returned by List or Create).

Response

• {{<stepReference>.response.data.data.redirects.deleteRedirects.deletedRedirectEntityIds}} — array of ids actually deleted.
• {{<stepReference>.response.data.data.redirects.deleteRedirects.errors}} — mutation-level errors, e.g. an id that doesn't exist.

Example

To delete a single redirect, use the id from a prior "List URL Redirects" step: {"input": {"siteId": 1, "entityIds": [{{listRedirects.response.data.data.store.redirects.edges.0.node.entityId}}]}}.