BigCommerce Admin GraphQL

What this connector is

A thin, editable window onto BigCommerce's Admin GraphQL API — the part of the platform (store settings, URL redirects, metafields, channels) that the REST API doesn't cover. Every request is a GraphQL document you can change. If you need products, orders or customers, use the BigCommerce (REST) connector alongside it.

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

Connecting

Use the same credentials as the BigCommerce (REST) connector:

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

Create the credentials under Advanced Settings → API Accounts, with the scopes each query or mutation you plan to run needs. If either value is missing, the action fails with an error pointing you there.

Your first call

1. Add a step with the Admin GraphQL: Get Store Settings action and name it "Get Store Settings" (reference getStoreSettings).
2. Pick your BigCommerce connection and leave the default query as is, or trim it to just what you need, for example store { name primaryDomain { host } }.
3. Run the workflow and read the store name in a later step with {{getStoreSettings.response.data.data.store.name}}.
4. Check {{getStoreSettings.response.data.errors}} before relying on the data — see Reading the response and GraphQL errors.

Every action, with its parameters and response fields, is listed in the action reference.

How actions are organised

There are five actions:

• Admin GraphQL: Execute Query — run any query or mutation you write.
• Admin GraphQL: Get Store Settings — a ready-made store settings query.
• Admin GraphQL: List URL Redirects, Create URL Redirect and Delete URL Redirect — ready-made redirect operations.

The four named actions are the same mechanism as Execute Query, pre-loaded with a useful default document.

The editable query/variables pattern

Unlike a typical fixed-input action, each action exposes two inputs:

• GraphQL Query (or GraphQL Mutation) — the document sent to BigCommerce. It is fully editable: add or remove fields, change filters, or replace the operation with any other query or mutation the Admin GraphQL API supports. On the four named actions, leaving it blank falls back to the default.
• Variables — a JSON string of GraphQL variables, for example {"first": 10}. It is parsed with JSON.parse before sending, so it must be valid JSON; invalid JSON fails the step with an "Invalid variables JSON" error.

Use an action as-is for its default behaviour, or rewrite the document to select different fields, add pagination arguments, or run a different operation from the same area of the schema.

Quirks and exceptions

• Execute Query has no default. Its query field is required; the example shown in the editor is only placeholder text, and no variables are sent unless you supply them (an empty {} goes out).
• Get Store Settings has no Variables field, because its default query declares no $ arguments. If you edit the query to take variables, use Execute Query instead.
• The redirect actions each ship with both a default document and default variables; edit the variables (not the document) for normal use.

Reading the response and GraphQL errors

Every action returns the same envelope, read 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. It is usually 200 even when the GraphQL operation failed, because GraphQL reports errors in the body.
• {{<stepReference>.response.headers.<header-name>}} — a response header.
• {{<stepReference>.response.data.data.<field path>}} — your queried data. The first .data unwraps the connector's HTTP envelope; the second is GraphQL's own { data, errors } wrapper, so you always see .data.data before the fields your query selected.
• {{<stepReference>.response.data.errors}} — an array of GraphQL errors (bad field name, validation failure). Check it even when the status is 200.

Mutations add a second level of errors: the redirect mutations return an errors { message } list inside their own payload, for example {{createRedirect.response.data.data.redirects.createRedirects.errors}} for a fromPath that already has a redirect. These are distinct from the top-level response.data.errors, so check both.

Pagination

Queries that return connections (such as redirects) take first and after variables and return pageInfo { hasNextPage endCursor }. To get the next page, run the action again with after set to the previous page's endCursor. The default List URL Redirects variables set first and filter.siteId but not after; add it yourself.

Common tasks

Add redirects after a URL change

1. Run List URL Redirects (named "List Redirects", reference listRedirects) with variables {"first": 50, "filter": {"siteId": 1}} to see what already exists. The redirect list is at {{listRedirects.response.data.data.store.redirects.edges}}.
2. Run Create URL Redirect with variables like the following. Add more entries to redirects to create several at once. statusCode is 301 for permanent and 302 for temporary.

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

3. Read the new id with {{createRedirect.response.data.data.redirects.createRedirects.redirects.0.entityId}}.

Remove a redirect you just found

1. Run List URL Redirects.
2. Run Delete URL Redirect with the id from step 1:

{ "input": { "siteId": 1, "entityIds": [{{listRedirects.response.data.data.store.redirects.edges.0.node.entityId}}] } }

3. Confirm with {{deleteRedirect.response.data.data.redirects.deleteRedirects.deletedRedirectEntityIds}}.

Run any other Admin GraphQL operation

Use Admin GraphQL: Execute Query and paste the full document into GraphQL Query and its variables into Variables, for example a metafields or channels query not covered by the other four actions.