BigCommerce

Manage your BigCommerce store — catalog, orders, customers, coupons, price lists, and inventory — via the Admin REST API (v2 + v3). Covers connecting, v2 vs v3 response shapes, pagination, quirks, and common workflows.

Open in Claude

Browse 38 BigCommerce actions bigcommerce

On this page

Connecting Your first call How actions are organised Reading the response Delete actions Pagination and ordering Quirks and exceptions Error handling Common tasks Add a product to a category and set its price list price Fulfil orders awaiting shipment Retire a promotion Step Name Step Reference Execution Settings Caching Locking

BigCommerce is the Admin REST connector for your store: catalog (products, variants, categories, brands), price lists, inventory, customers, orders, shipments, and coupons. It calls the v3 API for catalog, price lists, inventory and customers, and the v2 API for orders and coupons. Every action, with its parameters and response fields, is listed in the action reference.

Connecting

Every action needs a BigCommerce connection configured with:

Store Hash — the identifier in your store's API URL (https://api.bigcommerce.com/stores/<store-hash>/...).
Access Token — created under Advanced Settings → API Accounts in the BigCommerce control panel.

There is no per-action header configuration. The access token is sent as the X-Auth-Token header on every request automatically.

Your first call

Add a BigCommerce step and choose Get Product. Name the step "Get Product" so its reference is getProduct.
Set Product ID to 1042 and Include to variants,images.
In a later step, read the product with {{getProduct.response.data.data.name}} and its variants with {{getProduct.response.data.data.variants}}.

Note the doubled data: this is a v3 endpoint. See "Reading the response" below.

How actions are organised

Actions follow the BigCommerce resource they manage: Products, Product Variants, Categories, Brands, Price Lists, Inventory, Customers, Orders, and Coupons. Most resources have Get / List / Create / Update / Delete actions. Each action's reference page shows which fields are path parameters, query parameters, or body fields.

Reading the response

Every action's result lands at {{<stepReference>.response...}} (see Step Reference), in the same envelope regardless of API version: .response.status, .response.statusText, .response.headers.<header-name>, and .response.data for the body.

What is inside .response.data depends on the BigCommerce API version:

v3 endpoints (Products, Variants, Categories, Brands, Price Lists, Inventory, Customers) wrap every body in {"data": ..., "meta": ...}, even for a single resource. A single resource's fields are at {{getProduct.response.data.data.<field>}}, a list is an array at {{listProducts.response.data.data}}, and pagination info is at {{listProducts.response.data.meta}}.
v2 endpoints (Orders, Coupons) return the resource directly: {{getOrder.response.data.status}}. A list is a plain array at {{listOrders.response.data}} with no meta. v2 reports counts in response headers instead (e.g. {{listOrders.response.headers['x-total-count']}}).

Delete actions

On success, Delete Product, Delete Product Variant, Delete Category, Delete Customer, and Delete Coupon return a bare { "success": true } directly, not the envelope. Read {{deleteCategory.response.success}}. Delete Product also returns productId alongside it. If BigCommerce returns an error, the normal envelope comes back instead, so .response.status only resolves in that failure case.

Pagination and ordering

List actions take Limit (default 50) and Page (default 1). Page by re-running the step with an incremented page.
v3 lists report totals in .response.data.meta.pagination (e.g. meta.pagination.total). v2 lists (List Orders, List Coupons) have no meta; use the x-total-count header.
List Orders sorts by date_created:desc unless you set Sort. Created After / Created Before take RFC 2822 date strings.
Get Order Products returns a plain array with no pagination metadata.

Quirks and exceptions

Field names differ from the wire. In List Products, Category ID is sent to BigCommerce as the categories:in query parameter, not category_id.
JSON-string fields. Fields such as categories, option_values, records, items, and applies_to are entered as JSON text and parsed before sending. Numeric fields are parsed to numbers.
Create Customer sends an array containing one customer object, because /customers on v3 is a batch endpoint. A Password, if set, is sent as authentication.new_password with force_password_reset: false, not as a plain password field.
Customer actions on v3 respond with arrays, even for one customer. Read {{createCustomer.response.data.data[0].id}}, {{getCustomer.response.data.data[0].email}}, {{updateCustomer.response.data.data[0].company}}.
Customer ID is not a path segment. Get Customer and Delete Customer send it as the id:in query filter (Get is a filtered GET /customers, Delete a filtered DELETE /customers). Update Customer sends it as id inside the request body (a batch PUT), and the body is an array with the single updated object.
List Customers filters: Email Filter is sent as email:in, Company Filter as company:in, and Customer Group ID as plain customer_group_id with no :in.
Upsert Price List Records sends the parsed Records array as the entire PUT body, not wrapped in an object. Set Inventory Absolute sends the parsed array as the items property ({ items: [...] }). Neither response has a meta field.
Update actions send only the fields you set, so unset fields are left unchanged.
Order status IDs. List Orders filters use 0=Incomplete, 1=Pending, 2=Shipped, 10=Completed, 11=Awaiting Fulfillment. Update Order accepts 1=Pending, 2=Shipped, 5=Cancelled, 10=Completed.
Coupon amounts. For percentage_discount the Amount is a percentage; for the other coupon types it is a currency amount.
Create Order Shipment is v2: the shipment is at {{createOrderShipment.response.data.id}} with no extra wrapper.

Error handling

Non-2xx responses from BigCommerce do not fail the step. They are returned as a normal result with the real status code, so you can branch on {{<stepReference>.response.status}} exactly like the HTTP Connector. A network failure (BigCommerce unreachable) is returned as a synthetic 503, and any other unexpected error as a synthetic 500, both in the same envelope shape rather than throwing.

Common tasks

Add a product to a category and set its price list price

Create Product with Name, Type, Price, Weight, and Category IDs [12]. Name the step "Create Product".
Create Product Variant with Product ID {{createProduct.response.data.data.id}}, a SKU, and Option Values.
Upsert Price List Records with Price List ID 7 and Records [{"variant_id": {{createProductVariant.response.data.data.id}}, "price": 59.99, "currency": "USD"}].

Fulfil orders awaiting shipment

List Orders with Status ID 11 and Limit 25. Loop over {{listOrders.response.data}}.
Get Order Products for each order to get the line items at {{getOrderProducts.response.data}}.
Create Order Shipment with the order's order_address_id, Items listing order_product_id and quantity, and a tracking number and carrier.
Update Order with Status ID 2 and optional Staff Notes.

Retire a promotion

List Coupons with Code Filter SUMMER10. Read the ID at {{listCoupons.response.data[0].id}}.
Update Coupon with that Coupon ID and Enabled set to false.

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}}:

text

{{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:

text

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

Referencing trigger data

text

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

Referencing workflow variables

text

{{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:

text

{{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.

Was this page helpful?

Last updated 9 October 2026