Menu
Connectors
BigCommerce
Manage your BigCommerce store — catalog, orders, customers, coupons, price lists, and inventory — via the Admin REST API (v2 + v3). Covers path/query/body parameters and response shapes for every action.
On this page
Authentication
Every action needs a BigCommerce connection configured with:
- Store Hash — the identifier in your BigCommerce 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's no per-action header configuration — the connection's access token is sent as the X-Auth-Token header on every request automatically.
Reading the response
Every action's result lands at {{<stepReference>.response...}} (see Step Reference), wrapped in the same envelope regardless of which BigCommerce API version it calls: {{<stepReference>.response.status}}, {{<stepReference>.response.statusText}}, {{<stepReference>.response.headers.<header-name>}}, and {{<stepReference>.response.data.<field>}} for the response body.
BigCommerce's own API shape differs by version, which changes how deep you need to go inside .response.data:
- v3 endpoints (Products, Variants, Categories, Brands, Price Lists, Inventory, and the v3-based Customers actions) wrap every response body in
{"data": ..., "meta": ...}, even for a single resource by ID — so a single resource's fields are at{{<stepReference>.response.data.data.<field>}}(three levels: the envelope's.data, then BigCommerce's own.data, then the field), a list is an array at{{<stepReference>.response.data.data}}, and pagination info is at{{<stepReference>.response.data.meta}}. - v2 endpoints (Orders, Coupons) return the resource directly with no extra wrapper — a single resource's fields are at
{{<stepReference>.response.data.<field>}}(two levels), and a list is a plain array directly at{{<stepReference>.response.data}}with nometa— v2 communicates result counts via response headers instead (e.g.{{<stepReference>.response.headers['x-total-count']}}), so paging through v2 results means re-running the step with an incrementedpage.
Each action below states its own exact access path so you don't have to work this out per call.
Delete actions are the one exception to this envelope. On success, every "Delete" action in this connector (Delete Product, Delete Product Variant, Delete Category, Delete Customer, Delete Coupon) returns a plain { "success": true } object directly — not the .response.data... envelope — so use {{<stepReference>.response.success}}. If BigCommerce returns an error instead, the normal envelope shape is returned, so {{<stepReference>.response.status}} only resolves in that failure case.
Error handling
Non-2xx responses from BigCommerce do not fail the step — they're returned as a normal result with the real status code, so you can branch on {{<stepReference>.response.status}} in the workflow, 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 still in the same envelope shape rather than throwing.
Get Product
Retrieve a single product by ID from the BigCommerce catalog.
Path Parameters
- Product ID (
productId) — the BigCommerce product ID to fetch. Required.
Query Parameters
- Include (
include) — comma-separated list of sub-resources to include (e.g.images,variants,custom_fields,options,modifiers), sent to BigCommerce as theincludequery parameter. Optional.
Response
The product is available at {{getProduct.response.data.data.id}}, {{getProduct.response.data.data.name}}, {{getProduct.response.data.data.sku}}, etc. — getProduct.response is the HTTP envelope, its .data is BigCommerce's v3 wrapper, and that wrapper's own .data is the product object.
Example
Set Product ID to 1042 and Include to variants,images to fetch product 1042 along with its variants and images in one call.
List Products
List catalog products with filtering, sorting, and pagination.
Query Parameters
- Keyword Search (
keyword) — free-text search, sent as thekeywordquery parameter. Optional. - Category ID (
category_id) — filters to products in a category; sent to BigCommerce as thecategories:inquery parameter, notcategory_id. Optional. - Brand ID (
brand_id) — sent as thebrand_idquery parameter. Optional. - Availability (
availability) — one ofavailable,disabled,preorder. Optional. - Featured Only (
is_featured) — sent as theis_featuredboolean query parameter. Optional. - Min Price (
price_min) — sent asprice_min. Optional. - Max Price (
price_max) — sent asprice_max. Optional. - Sort Field (
sort) — sent assort. Optional. - Sort Direction (
direction) —ascordesc, sent asdirection. Optional. - Limit (
limit) — page size, sent aslimit. Defaults to50if left blank. - Page (
page) — sent aspage. Defaults to1if left blank. - Include (
include) — comma-separated sub-resources, sent asinclude. Optional.
Response
Matching products are an array at {{listProducts.response.data.data}} (e.g. {{listProducts.response.data.data[0].name}}), and pagination info is at {{listProducts.response.data.meta}}.
Example
Set Category ID to 12, Availability to available, Sort Field to price, Sort Direction to asc, and Limit to 25 to page through available products in category 12, cheapest first.
Create Product
Create a new product in the BigCommerce catalog.
Request Body
- Name (
name) — required. - Type (
type) —physicalordigital. Required. - Price (
price) — required, sent as a number. - Weight (oz) (
weight) — required, sent as a number. - SKU (
sku) — optional. - Description (HTML) (
description) — optional. - Category IDs (
categories) — a JSON array of category IDs as a string (e.g.[12, 15]), parsed and sent ascategories. Optional. - Brand ID (
brand_id) — optional, sent as a number. - Availability (
availability) —available,disabled, orpreorder. Defaults toavailableif left blank. - Featured (
is_featured) — defaults tofalse. - Visible in Storefront (
is_visible) — defaults totrue. - Inventory Level (
inventory_level) — optional, sent as a number. - Inventory Tracking (
inventory_tracking) —none,product, orvariant. Defaults tononeif left blank.
Response
The created product is available at {{createProduct.response.data.data.id}} and {{createProduct.response.data.data.sku}}.
Example
Set Name to Running Shoe X, Type to physical, Price to 79.99, Weight (oz) to 12, SKU to SHOE-001, and Category IDs to [12] to add a new physical product to category 12.
Update Product
Update an existing BigCommerce product.
Path Parameters
- Product ID (
productId) — the product to update. Required.
Request Body
All fields below are optional — only the ones set are sent, so unset fields on the existing product are left unchanged.
- Name (
name) - Price (
price) — sent as a number. - SKU (
sku) - Description (HTML) (
description) - Availability (
availability) —available,disabled, orpreorder. - Featured (
is_featured) - Visible (
is_visible) - Inventory Level (
inventory_level) — sent as a number. - Brand ID (
brand_id) — sent as a number. - Category IDs (JSON array) (
categories) — a JSON array string, parsed before being sent ascategories.
Response
The updated product is available at {{updateProduct.response.data.data.id}} and its updated fields, e.g. {{updateProduct.response.data.data.price}}.
Example
Set Product ID to 1042, Price to 69.99, and Availability to disabled to discount and unpublish an existing product.
Delete Product
Permanently delete a product from the BigCommerce catalog.
Path Parameters
- Product ID (
productId) — the product to delete. Required.
Response
On success this action returns a plain { success: true, productId } object directly (see the note on delete actions in "Reading the response" above) — use {{deleteProduct.response.success}} and {{deleteProduct.response.productId}}, not .response.data.... If BigCommerce returns an error, the normal envelope shape is returned instead.
Example
Set Product ID to 1042 to permanently remove that product from the catalog.
Create Product Variant
Add a new variant to a BigCommerce product.
Path Parameters
- Product ID (
productId) — the parent product, interpolated into/catalog/products/{productId}/variants. Required.
Request Body
- SKU (
sku) — required. - Option Values (
option_values) — required, a JSON array string such as[{"id": 1, "option_id": 1}], parsed and sent asoption_values. - Price Override (
price) — optional, sent asprice. - Weight Override (
weight) — optional, sent asweight. - Inventory Level (
inventory_level) — optional, sent as a number. - UPC/EAN (
upc) — optional. - Image URL (
image_url) — optional.
Response
The created variant is available at {{createProductVariant.response.data.data.id}} and {{createProductVariant.response.data.data.sku}}.
Example
Set Product ID to 1042, SKU to SHOE-001-L-BLU, and Option Values to [{"id": 5, "option_id": 2}] to add a Large/Blue variant to that product.
List Product Variants
Get all variants for a BigCommerce product.
Path Parameters
- Product ID (
productId) — required.
Query Parameters
- Limit (
limit) — page size, defaults to50if left blank. - Page (
page) — defaults to1if left blank.
Response
Variants are an array at {{listProductVariants.response.data.data}} (e.g. {{listProductVariants.response.data.data[0].sku}}), with pagination info at {{listProductVariants.response.data.meta}}.
Example
Set Product ID to 1042 and Limit to 100 to fetch up to 100 variants for that product.
Update Product Variant
Update a BigCommerce product variant's price, SKU, or inventory.
Path Parameters
- Product ID (
productId) — required. - Variant ID (
variantId) — required.
Request Body
All fields below are optional.
- SKU (
sku) - Price (
price) — sent as a number. - Weight (
weight) — sent as a number. - Inventory Level (
inventory_level) — sent as a number. - UPC/EAN (
upc) - Image URL (
image_url)
Response
The updated variant is available at {{updateProductVariant.response.data.data.id}} and, e.g., {{updateProductVariant.response.data.data.price}}.
Example
Set Product ID to 1042, Variant ID to 501, and Price to 74.99 to reprice one specific variant.
Delete Product Variant
Remove a variant from a BigCommerce product.
Path Parameters
- Product ID (
productId) — required. - Variant ID (
variantId) — required.
Response
Like Delete Product, this returns a plain { success: true } object on success rather than the envelope — use {{deleteProductVariant.response.success}}.
Example
Set Product ID to 1042 and Variant ID to 501 to delete that variant.
Get Category
Retrieve a single category by ID.
Path Parameters
- Category ID (
categoryId) — required.
Response
The category is available at {{getCategory.response.data.data.id}} and {{getCategory.response.data.data.name}}.
Example
Set Category ID to 12 to fetch that category's details.
List Categories
List all categories in the BigCommerce catalog tree.
Query Parameters
- Parent Category ID (
parent_id) — filters by parent category (0= top-level); sent asparent_id. Optional. - Name Filter (
name) — sent asname. Optional. - Visible Only (
is_visible) — sent asis_visible. Optional. - Limit (
limit) — defaults to50if left blank. - Page (
page) — defaults to1if left blank.
Response
Categories are an array at {{listCategories.response.data.data}} (e.g. {{listCategories.response.data.data[0].name}}), with pagination info at {{listCategories.response.data.meta}}.
Example
Set Parent Category ID to 0 to list all top-level categories.
Create Category
Create a new category in BigCommerce.
Request Body
- Name (
name) — required. - Parent Category ID (
parent_id) —0= top level. Defaults to0if left blank. - Description (HTML) (
description) — optional. - Visible (
is_visible) — defaults totrue. - Sort Order (
sort_order) — optional, sent as a number. - Page Title (SEO) (
page_title) — optional. - Meta Description (SEO) (
meta_description) — optional.
Response
The created category is available at {{createCategory.response.data.data.id}} and {{createCategory.response.data.data.name}}.
Example
Set Name to Running Shoes and Parent Category ID to 0 to create a new top-level category.
Update Category
Update a BigCommerce category.
Path Parameters
- Category ID (
categoryId) — required.
Request Body
All fields below are optional.
- Name (
name) - Description (
description) - Visible (
is_visible) - Sort Order (
sort_order) — sent as a number. - Parent Category ID (
parent_id) — sent as a number.
Response
The updated category is available at {{updateCategory.response.data.data.id}} and its updated fields, e.g. {{updateCategory.response.data.data.name}}.
Example
Set Category ID to 12 and Name to Men's Running Shoes to rename that category.
Delete Category
Delete a BigCommerce category.
Path Parameters
- Category ID (
categoryId) — required.
Response
As with the other delete actions, this returns a plain { success: true } object on success — use {{deleteCategory.response.success}}.
Example
Set Category ID to 12 to delete that category.
Create Brand
Create a new brand in BigCommerce.
Request Body
- Name (
name) — required. - Page Title (
page_title) — optional. - Meta Description (
meta_description) — optional. - Brand Logo URL (
image_url) — optional.
Response
The created brand is available at {{createBrand.response.data.data.id}} and {{createBrand.response.data.data.name}}.
Example
Set Name to Nike and Brand Logo URL to https://example.com/logos/nike.png to create a new brand.
List Brands
List product brands in BigCommerce.
Query Parameters
- Name Filter (
name) — sent asname. Optional. - Limit (
limit) — defaults to50if left blank. - Page (
page) — defaults to1if left blank.
Response
Brands are an array at {{listBrands.response.data.data}} (e.g. {{listBrands.response.data.data[0].name}}), with pagination info at {{listBrands.response.data.meta}}.
Example
Set Name Filter to Nike to search for brands matching that name.
Create Price List
Create a new price list for B2B or customer group pricing.
Request Body
- Name (
name) — required. - Active (
active) — defaults totrueif left blank.
Response
The created price list is available at {{createPriceList.response.data.data.id}} and {{createPriceList.response.data.data.name}}. Use its ID with Upsert Price List Records to add product prices to it.
Example
Set Name to Wholesale Pricing and Active to true to create a new price list for wholesale customers.
List Price Lists
List BigCommerce price lists (for B2B/customer group pricing).
Query Parameters
- Name Filter (
name) — sent asname. Optional. - Limit (
limit) — defaults to50if left blank. - Page (
page) — defaults to1if left blank.
Response
Price lists are an array at {{listPriceLists.response.data.data}} (e.g. {{listPriceLists.response.data.data[0].name}}), with pagination info at {{listPriceLists.response.data.meta}}.
Example
Set Name Filter to Wholesale to find price lists matching that name.
Upsert Price List Records
Add or update product prices in a BigCommerce price list.
Path Parameters
- Price List ID (
priceListId) — interpolated into/pricelists/{priceListId}/records. Required.
Request Body
- Records (
records) — required, a JSON array string such as[{"variant_id": 1, "price": 25.99, "currency": "USD"}]. The parsed array is sent as the entire PUT request body — it is not wrapped in a containing object.
Response
Updated records are an array at {{upsertPriceListRecords.response.data.data}} (e.g. {{upsertPriceListRecords.response.data.data[0].price}}); this endpoint's output has no meta field.
Example
Set Price List ID to 7 and Records to [{"variant_id": 501, "price": 59.99, "currency": "USD"}] to set a wholesale price for variant 501.
Get Inventory
Retrieve inventory levels across BigCommerce locations.
Query Parameters
- Product ID (
product_id) — sent asproduct_id. Optional. - Variant ID (
variant_id) — sent asvariant_id. Optional. - Location ID (
location_id) — sent aslocation_id. Optional. - Limit (
limit) — defaults to50if left blank. - Page (
page) — defaults to1if left blank.
Response
Inventory items are an array at {{getInventory.response.data.data}} (e.g. {{getInventory.response.data.data[0].available_to_sell}}), with pagination info at {{getInventory.response.data.meta}}.
Example
Set Product ID to 1042 and Location ID to 1 to check that product's stock at a specific location.
Set Inventory Absolute
Set inventory to exact quantities across BigCommerce locations.
Request Body
- Items (
items) — required, a JSON array string such as[{"variant_id": 1, "location_id": 1, "quantity": 50}]. The parsed array is sent as theitemsproperty of the PUT request body ({ items: [...] }).
Response
Updated inventory records are an array at {{setInventoryAbsolute.response.data.data}} (e.g. {{setInventoryAbsolute.response.data.data[0].quantity}}); this endpoint's output has no meta field.
Example
Set Items to [{"variant_id": 501, "location_id": 1, "quantity": 75}] to set variant 501's stock at location 1 to exactly 75 units.
Create Customer
Create a new BigCommerce customer account.
Request Body
- Email (
email) — the customer's email address; required. - First Name (
first_name) — required. - Last Name (
last_name) — required. - Password (
password) — optional; when set, it is sent asauthentication.new_password(withforce_password_reset: false), not as a plainpasswordfield. - Phone (
phone) — optional. - Company (
company) — optional. - Customer Group ID (
customer_group_id) — optional; parsed to a number before being sent ascustomer_group_id. - Notes (
notes) — optional, multi-line text.
The request BigCommerce actually receives is an array containing one customer object — /customers on v3 is a batch-create endpoint — even though the UI only configures a single customer.
Response
This action uses the v3 client, so the created customer's fields are at {{createCustomer.response.data.data[0].id}}, {{createCustomer.response.data.data[0].email}}, etc. — note the [0], since v3's customer endpoints always respond with an array even for a single customer.
Example
Email=jane@example.com, First Name=Jane, Last Name=Doe, Customer Group ID=3. A later step can reference the new customer's ID as {{createCustomer.response.data.data[0].id}}.
Delete Customer
Delete a BigCommerce customer account.
Query Parameters
- Customer ID (
customerId) — required. Despite the field name, this is not a URL path segment: it is sent as theid:inquery filter on aDELETE /customersrequest, since BigCommerce's v3 customer deletion is a filtered batch operation, not a single-resource path.
Response
On success this action returns a plain { success: true } object directly (see the delete-action note in "Reading the response" above). Only a non-2xx BigCommerce response falls back to the normal envelope shape, readable as {{deleteCustomer.response.status}}.
Example
Customer ID=482. On success, the step output is simply {"success": true}.
Get Customer
Retrieve a BigCommerce customer by ID.
Query Parameters
- Customer ID (
customerId) — required; sent as theid:infilter onGET /customers, not a URL path segment. - Include (
include) — optional, e.g.addresses,formfields; sent as theincludequery param.
Response
Because this is a filtered collection lookup rather than a single-resource path, the matched customer is the first element of BigCommerce's v3 wrapper array: {{getCustomer.response.data.data[0].email}}, {{getCustomer.response.data.data[0].addresses}}, etc.
Example
Customer ID=482, Include=addresses. Reference the email as {{getCustomer.response.data.data[0].email}}.
List Customers
List BigCommerce customers with optional filters.
Query Parameters
- Email Filter (
email) — optional; sent asemail:in. - Company Filter (
company) — optional; sent ascompany:in. - Customer Group ID (
customer_group_id) — optional; parsed to a number, sent ascustomer_group_id(no:insuffix). - Include (
include) — optional, e.g.addresses. - Limit (
limit) — optional, defaults to50. - Page (
page) — optional, defaults to1.
Response
The array of customers is at {{listCustomers.response.data.data}}, and pagination metadata is at {{listCustomers.response.data.meta}} (e.g. meta.pagination.total).
Example
Company Filter=Acme Corp, Limit=25. Iterate {{listCustomers.response.data.data}} in a loop step.
Update Customer
Update a BigCommerce customer's profile.
Request Body
- Customer ID (
customerId) — required. Sent asidinside the request body, not a URL path segment — BigCommerce's v3 customers endpoint updates via a batchPUTkeyed byid. - First Name (
first_name) — optional. - Last Name (
last_name) — optional. - Email (
email) — optional. - Phone (
phone) — optional. - Company (
company) — optional. - Group ID (
customer_group_id) — optional; parsed to a number, sent ascustomer_group_id. - Notes (
notes) — optional.
The body BigCommerce receives is an array containing the single updated-fields object.
Response
Same shape as Get/List Customer: {{updateCustomer.response.data.data[0].id}}.
Example
Customer ID=482, Company=Acme Corp. Reference the updated value as {{updateCustomer.response.data.data[0].company}}.
Create Order Shipment
Mark BigCommerce order items as shipped with tracking info.
Path Parameters
- Order ID (
orderId) — required; interpolated into the URL as/orders/{orderId}/shipments.
Request Body
- Order Address ID (
order_address_id) — required; parsed to a number, sent asorder_address_id. - Items (
items) — required; a JSON array string, e.g.[{"order_product_id": 1, "quantity": 2}], parsed and sent asitems. - Tracking Number (
tracking_number) — optional. - Carrier (
tracking_carrier) — optional, e.g.fedex,ups,usps; sent astracking_carrier. - Comments (
comments) — optional.
Response
This action uses the v2 client, which returns the resource directly with no extra wrapper: {{createOrderShipment.response.data.id}} (shipment ID) and {{createOrderShipment.response.data.tracking_number}}.
Example
Order ID=1042, Order Address ID=1, Items=[{"order_product_id": 501, "quantity": 1}], Tracking Number=1Z999AA10123456784, Carrier=ups.
Get Order
Retrieve a single BigCommerce order by ID.
Path Parameters
- Order ID (
orderId) — required; interpolated into the URL as/orders/{orderId}.
Response
v2 client — flat shape, no extra wrapper: {{getOrder.response.data.status}}, {{getOrder.response.data.total_inc_tax}}, {{getOrder.response.data.customer_id}}, {{getOrder.response.data.billing_address}}.
Example
Order ID=1042. Branch a later step on {{getOrder.response.data.status}}.
Get Order Products
Get the line items for a BigCommerce order.
Path Parameters
- Order ID (
orderId) — required; interpolated into the URL as/orders/{orderId}/products.
Response
BigCommerce returns a plain JSON array with no {data, meta} wrapper for this v2 endpoint, so {{getOrderProducts.response.data}} is the array of line items — index or iterate it directly, e.g. {{getOrderProducts.response.data[0].name}}, {{getOrderProducts.response.data[0].quantity}}. No pagination metadata is returned for this endpoint.
Example
Order ID=1042. Loop over {{getOrderProducts.response.data}} to process each line item.
List Orders
List BigCommerce orders with filters.
Query Parameters
- Status ID (
status_id) — optional numeric filter (0=Incomplete,1=Pending,2=Shipped,10=Completed,11=Awaiting Fulfillment). - Customer ID (
customer_id) — optional numeric filter. - Created After (
min_date_created) — optional, RFC 2822 date string. - Created Before (
max_date_created) — optional, RFC 2822 date string. - Sort (
sort) — optional, defaults todate_created:desc. - Limit (
limit) — optional, defaults to50. - Page (
page) — optional, defaults to1.
Response
A plain array at {{listOrders.response.data}}, with no meta field in the body — BigCommerce's v2 API communicates result counts via response headers instead (e.g. {{listOrders.response.headers['x-total-count']}}); paging through results means re-running the step with an incremented page.
Example
Status ID=11, Limit=25, Sort=date_created:desc — to pull orders awaiting fulfillment.
Update Order
Update a BigCommerce order status or staff notes.
Path Parameters
- Order ID (
orderId) — required; interpolated into the URL as/orders/{orderId}.
Request Body
- Status ID (
status_id) — optional numeric (1=Pending,2=Shipped,5=Cancelled,10=Completed); parsed to a number, sent asstatus_id. - Staff Notes (
staff_notes) — optional, internal-only notes. - Customer Message (
customer_message) — optional, sent ascustomer_message.
Response
Flat v2 shape: {{updateOrder.response.data.id}}, {{updateOrder.response.data.status}}.
Example
Order ID=1042, Status ID=2, Staff Notes=Shipped via UPS ground.
Create Coupon
Create a new discount coupon in BigCommerce.
Request Body
- Name (
name) — required. - Code (
code) — required; the code shoppers enter at checkout. - Type (
type) — required; one ofper_item_discount,percentage_discount,per_total_discount,shipping_discount,free_shipping. - Amount (
amount) — required; parsed to a number. A percentage forpercentage_discount, a currency amount for the others. - Enabled (
enabled) — optional, defaults totrue. - Max Total Uses (
max_uses) — optional; parsed to a number. - Max Uses Per Customer (
max_uses_per_customer) — optional; parsed to a number. - Min Order Amount (
min_purchase) — optional; parsed to a number, sent asmin_purchase. - Expires (
expires) — optional, RFC 2822 date string. - Applies To (
applies_to) — optional; a JSON object string, e.g.{"entity":"categories","ids":[12]}, parsed and sent asapplies_to.
Response
Flat v2 shape: {{createCoupon.response.data.id}}, {{createCoupon.response.data.code}}.
Example
Name=Summer 10% Off, Code=SUMMER10, Type=percentage_discount, Amount=10, Max Uses Per Customer=1, Expires=Mon, 31 Aug 2026 23:59:59 +0000.
Delete Coupon
Delete a BigCommerce coupon code.
Path Parameters
- Coupon ID (
couponId) — required; interpolated into the URL as/coupons/{couponId}.
Response
Like Delete Customer, this returns a plain { success: true } object on success; only an error response surfaces the usual {{deleteCoupon.response.status}} shape.
Example
Coupon ID=77.
List Coupons
List all discount coupons in BigCommerce.
Query Parameters
- Code Filter (
code) — optional, sent ascode. - Type Filter (
type) — optional (per_item_discount,percentage_discount,per_total_discount,shipping_discount,free_shipping). - Enabled Only (
enabled) — optional boolean, sent asenabled. - Limit (
limit) — optional, defaults to50. - Page (
page) — optional, defaults to1.
Response
A plain array at {{listCoupons.response.data}} with no meta wrapper, e.g. {{listCoupons.response.data[0].code}}.
Example
Type Filter=percentage_discount, Enabled Only=true, Limit=20.
Update Coupon
Update a BigCommerce coupon.
Path Parameters
- Coupon ID (
couponId) — required; interpolated into the URL as/coupons/{couponId}.
Request Body
- Name (
name) — optional. - Code (
code) — optional. - Amount (
amount) — optional; parsed to a number. - Enabled (
enabled) — optional boolean. - Max Uses (
max_uses) — optional; parsed to a number. - Expires (
expires) — optional, RFC 2822 date string.
Response
Flat v2 shape: {{updateCoupon.response.data.id}}, {{updateCoupon.response.data.code}}.
Example
Coupon ID=77, Enabled=false — to disable an expired promotion.
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.