younifyd
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
AuthenticationReading the responseError handlingGet ProductPath ParametersQuery ParametersResponseExampleList ProductsQuery ParametersResponseExampleCreate ProductRequest BodyResponseExampleUpdate ProductPath ParametersRequest BodyResponseExampleDelete ProductPath ParametersResponseExampleCreate Product VariantPath ParametersRequest BodyResponseExampleList Product VariantsPath ParametersQuery ParametersResponseExampleUpdate Product VariantPath ParametersRequest BodyResponseExampleDelete Product VariantPath ParametersResponseExampleGet CategoryPath ParametersResponseExampleList CategoriesQuery ParametersResponseExampleCreate CategoryRequest BodyResponseExampleUpdate CategoryPath ParametersRequest BodyResponseExampleDelete CategoryPath ParametersResponseExampleCreate BrandRequest BodyResponseExampleList BrandsQuery ParametersResponseExampleCreate Price ListRequest BodyResponseExampleList Price ListsQuery ParametersResponseExampleUpsert Price List RecordsPath ParametersRequest BodyResponseExampleGet InventoryQuery ParametersResponseExampleSet Inventory AbsoluteRequest BodyResponseExampleCreate CustomerRequest BodyResponseExampleDelete CustomerQuery ParametersResponseExampleGet CustomerQuery ParametersResponseExampleList CustomersQuery ParametersResponseExampleUpdate CustomerRequest BodyResponseExampleCreate Order ShipmentPath ParametersRequest BodyResponseExampleGet OrderPath ParametersResponseExampleGet Order ProductsPath ParametersResponseExampleList OrdersQuery ParametersResponseExampleUpdate OrderPath ParametersRequest BodyResponseExampleCreate CouponRequest BodyResponseExampleDelete CouponPath ParametersResponseExampleList CouponsQuery ParametersResponseExampleUpdate CouponPath ParametersRequest BodyResponseExampleStep NameStep ReferenceExecution SettingsCachingLocking

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 no meta — 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 incremented page.

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 the include query 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 the keyword query parameter. Optional.
  • Category ID (category_id) — filters to products in a category; sent to BigCommerce as the categories:in query parameter, not category_id. Optional.
  • Brand ID (brand_id) — sent as the brand_id query parameter. Optional.
  • Availability (availability) — one of available, disabled, preorder. Optional.
  • Featured Only (is_featured) — sent as the is_featured boolean query parameter. Optional.
  • Min Price (price_min) — sent as price_min. Optional.
  • Max Price (price_max) — sent as price_max. Optional.
  • Sort Field (sort) — sent as sort. Optional.
  • Sort Direction (direction) — asc or desc, sent as direction. Optional.
  • Limit (limit) — page size, sent as limit. Defaults to 50 if left blank.
  • Page (page) — sent as page. Defaults to 1 if left blank.
  • Include (include) — comma-separated sub-resources, sent as include. 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) — physical or digital. 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 as categories. Optional.
  • Brand ID (brand_id) — optional, sent as a number.
  • Availability (availability) — available, disabled, or preorder. Defaults to available if left blank.
  • Featured (is_featured) — defaults to false.
  • Visible in Storefront (is_visible) — defaults to true.
  • Inventory Level (inventory_level) — optional, sent as a number.
  • Inventory Tracking (inventory_tracking) — none, product, or variant. Defaults to none if 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, or preorder.
  • 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 as categories.

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 as option_values.
  • Price Override (price) — optional, sent as price.
  • Weight Override (weight) — optional, sent as weight.
  • 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 to 50 if left blank.
  • Page (page) — defaults to 1 if 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 as parent_id. Optional.
  • Name Filter (name) — sent as name. Optional.
  • Visible Only (is_visible) — sent as is_visible. Optional.
  • Limit (limit) — defaults to 50 if left blank.
  • Page (page) — defaults to 1 if 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 to 0 if left blank.
  • Description (HTML) (description) — optional.
  • Visible (is_visible) — defaults to true.
  • 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 as name. Optional.
  • Limit (limit) — defaults to 50 if left blank.
  • Page (page) — defaults to 1 if 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 to true if 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 as name. Optional.
  • Limit (limit) — defaults to 50 if left blank.
  • Page (page) — defaults to 1 if 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 as product_id. Optional.
  • Variant ID (variant_id) — sent as variant_id. Optional.
  • Location ID (location_id) — sent as location_id. Optional.
  • Limit (limit) — defaults to 50 if left blank.
  • Page (page) — defaults to 1 if 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 the items property 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 as authentication.new_password (with force_password_reset: false), not as a plain password field.
  • Phone (phone) — optional.
  • Company (company) — optional.
  • Customer Group ID (customer_group_id) — optional; parsed to a number before being sent as customer_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 the id:in query filter on a DELETE /customers request, 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 the id:in filter on GET /customers, not a URL path segment.
  • Include (include) — optional, e.g. addresses,formfields; sent as the include query 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 as email:in.
  • Company Filter (company) — optional; sent as company:in.
  • Customer Group ID (customer_group_id) — optional; parsed to a number, sent as customer_group_id (no :in suffix).
  • Include (include) — optional, e.g. addresses.
  • Limit (limit) — optional, defaults to 50.
  • Page (page) — optional, defaults to 1.

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 as id inside the request body, not a URL path segment — BigCommerce's v3 customers endpoint updates via a batch PUT keyed by id.
  • 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 as customer_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 as order_address_id.
  • Items (items) — required; a JSON array string, e.g. [{"order_product_id": 1, "quantity": 2}], parsed and sent as items.
  • Tracking Number (tracking_number) — optional.
  • Carrier (tracking_carrier) — optional, e.g. fedex, ups, usps; sent as tracking_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 to date_created:desc.
  • Limit (limit) — optional, defaults to 50.
  • Page (page) — optional, defaults to 1.

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 as status_id.
  • Staff Notes (staff_notes) — optional, internal-only notes.
  • Customer Message (customer_message) — optional, sent as customer_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 of per_item_discount, percentage_discount, per_total_discount, shipping_discount, free_shipping.
  • Amount (amount) — required; parsed to a number. A percentage for percentage_discount, a currency amount for the others.
  • Enabled (enabled) — optional, defaults to true.
  • 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 as min_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 as applies_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 as code.
  • Type Filter (type) — optional (per_item_discount, percentage_discount, per_total_discount, shipping_discount, free_shipping).
  • Enabled Only (enabled) — optional boolean, sent as enabled.
  • Limit (limit) — optional, defaults to 50.
  • Page (page) — optional, defaults to 1.

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.