# How to Integrate Retool with BigCommerce

- Tool: Retool
- Difficulty: Intermediate
- Time required: 20 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to BigCommerce using a REST API Resource with your store's API account access token. Configure the base URL using your BigCommerce store hash, then query the v2/v3 REST API to manage orders, products, customers, and storefront channels — building a faster, more focused admin panel than BigCommerce's native control panel for your operations team.

## Why Build a Retool BigCommerce Dashboard?

BigCommerce's built-in control panel is comprehensive but designed for a wide audience — merchants, marketers, and developers all use it for different tasks. Operations teams focused on order fulfillment, customer service, and inventory management often need a faster, more streamlined interface that shows exactly the data they need without navigating through BigCommerce's multi-section control panel. A Retool BigCommerce dashboard delivers that: a custom operations panel where your team can view, filter, and act on orders without touching the control panel at all.

Enterprise merchants on BigCommerce often operate across multiple storefronts (channels) and need a unified view of order volume, inventory status, and customer data across all channels. Retool can combine data from BigCommerce's channel-aware API with your internal warehouse management system, ERP, or CRM to show a complete picture. This is especially valuable for businesses that have integrated BigCommerce with third-party fulfillment providers and need to reconcile order status across systems.

BigCommerce's REST API is split between v2 (older, JSON-based, still used for orders and customers) and v3 (newer, with more detailed resources like catalog and channels). Retool handles both seamlessly through the same resource. The API uses cursor-based pagination for v3 and page-based pagination for v2, which transformers handle cleanly. Security is handled by Retool's server-side proxying — your BigCommerce access token never reaches the browser, critical for a store API that can write orders and update customer data.

## Before you start

- A Retool account (Cloud or self-hosted) with permission to add Resources
- A BigCommerce store (any plan — API access is available on all plans)
- A BigCommerce API account with the appropriate scopes — create in BigCommerce Control Panel → Advanced Settings → API Accounts → Create API Account
- Your BigCommerce API credentials: Client ID, Client Secret, and Access Token (shown once at account creation — save the access token immediately), plus your Store Hash from the store URL
- Understanding of BigCommerce's API split between v2 (orders, customers) and v3 (catalog, channels, carts) endpoints

## Step-by-step guide

### 1. Create a BigCommerce API account and configure the Resource

BigCommerce API accounts generate OAuth credentials that allow programmatic access to your store. Navigate to your BigCommerce Control Panel (store.mybigcommerce.com/manage) and go to Advanced Settings → API Accounts → Create V2/V3 API Token.

Configure the API account:
- Name: 'Retool Operations Dashboard'
- Select OAuth Scopes based on what your Retool dashboard needs:
  - Orders: Read-write (for order status updates and shipment creation)
  - Products: Read-write (for inventory and price updates)
  - Customers: Read-write (for customer lookup and credit adjustments)
  - Order Shipments: Read-write (for tracking number management)
  - Store Information: Read-only (for store configuration metadata)

Grant only the scopes your dashboard actually needs — if you're building a read-only monitoring dashboard, select Read-only for all scopes. Click Save. BigCommerce displays the Client ID, Client Secret, and Access Token together on a single screen. The Access Token is shown ONLY ONCE — copy it to a secure location immediately.

Identify your Store Hash from the BigCommerce control panel URL: it appears as the alphanumeric string in store.mybigcommerce.com/manage/STORE_HASH/ or in the API Account creation page.

Open Retool → Resources tab → Add Resource → REST API:
- Name: 'BigCommerce'
- Base URL: https://api.bigcommerce.com/stores/YOUR_STORE_HASH (replace YOUR_STORE_HASH with your actual store hash)
- Authentication: None (we use a header instead)
- Default Headers:
  - X-Auth-Token: your Access Token
  - Accept: application/json
  - Content-Type: application/json

Store the access token as a secret configuration variable (Settings → Configuration Variables → BIGCOMMERCE_ACCESS_TOKEN) and reference it as {{ retoolContext.configVars.BIGCOMMERCE_ACCESS_TOKEN }} in the header value.

Click Save Changes and Test Connection.

**Expected result:** The BigCommerce resource appears in the Resources list. Test Connection succeeds and returns a 200 response from the BigCommerce API base URL.

### 2. Query orders and build the order management table

Create a query to retrieve orders from BigCommerce's v2 Orders API. In your Retool app, go to the Code panel and create a new query. Select the BigCommerce resource. Configure:

- Method: GET
- Path: /v2/orders
- URL parameters:
  - status_id: {{ statusFilter.value || '' }} (filter by order status; BigCommerce uses numeric status IDs: 1=Pending, 2=Awaiting Payment, 3=Awaiting Fulfillment, 7=Awaiting Shipment, 8=Completed, 5=Cancelled)
  - min_date_created: {{ dateRange.start || '' }} (RFC 2822 format: Mon, 1 Jan 2024 00:00:00 +0000)
  - max_date_created: {{ dateRange.end || '' }}
  - sort: date_created:desc
  - limit: 50
  - page: {{ pagination.page || 1 }}

BigCommerce's v2 order response is an array of order objects each containing: id, customer_id, date_created, total_inc_tax, status, items_total, and billing_address. Add a JavaScript transformer to format dates, currency amounts, and extract the most relevant fields for the table.

Drag a Table component onto the canvas and bind its data to {{ ordersQuery.data }}. Add a Select component for status filtering populated with BigCommerce's status ID values and labels. Add date range pickers for the date filter. Enable row selection so clicking an order row loads the full order detail.

```
// Transformer for BigCommerce v2 orders response
const orders = Array.isArray(data) ? data : [];
const statusLabels = {
  0: 'Incomplete', 1: 'Pending', 2: 'Awaiting Payment',
  3: 'Awaiting Fulfillment', 4: 'Awaiting Shipment',
  5: 'Partially Shipped', 6: 'Awaiting Pickup', 7: 'Shipped',
  8: 'Completed', 9: 'Cancelled', 10: 'Declined',
  11: 'Refunded', 12: 'Disputed', 13: 'Manual Verification Required'
};
return orders.map(order => ({
  id: order.id,
  customer_id: order.customer_id,
  customer_name: `${order.billing_address?.first_name || ''} ${order.billing_address?.last_name || ''}`.trim(),
  customer_email: order.billing_address?.email || '',
  date_created: order.date_created
    ? new Date(order.date_created).toLocaleDateString()
    : '',
  total: parseFloat(order.total_inc_tax || 0).toLocaleString('en-US', { style: 'currency', currency: order.currency_code || 'USD' }),
  total_numeric: parseFloat(order.total_inc_tax || 0),
  items: order.items_total || 0,
  status_id: order.status_id,
  status: statusLabels[order.status_id] || order.status || '',
  channel_id: order.channel_id || 1,
  payment_method: order.payment_method || '',
  ip_address: order.ip_address || ''
}));
```

**Expected result:** A table populates with recent BigCommerce orders filtered by status and date range. Order details including customer name, total, item count, and status are displayed. Selecting an order row highlights it for detail view actions.

### 3. Add order detail view and status update capability

Build an order detail panel that loads when an order row is selected in the main table. Create two additional queries:

Order line items query:
- Method: GET
- Path: /v2/orders/{{ ordersTable.selectedRow.id }}/products
- Set to run automatically when ordersTable.selectedRow.id changes

Order shipping addresses query:
- Method: GET  
- Path: /v2/orders/{{ ordersTable.selectedRow.id }}/shippingaddresses

Display the order detail in a Container panel on the right side of the canvas. Show billing/shipping address, order line items in a nested table, payment method, and current status.

Create an order status update query:
- Method: PUT
- Path: /v2/orders/{{ ordersTable.selectedRow.id }}
- Body: { "status_id": {{ statusUpdateSelect.value }} }

Set to Manual trigger. Add a Select component for 'Change Status' with the status options. Wire a 'Save Status' button to trigger this query. Add event handlers: On Success → re-trigger ordersQuery to refresh the main table, show a notification 'Order {{ ordersTable.selectedRow.id }} status updated'.

For the shipment flow, create a 'Create Shipment' query:
- Method: POST
- Path: /v2/orders/{{ ordersTable.selectedRow.id }}/shipments
- Body with tracking number, carrier name, and items shipped

```
// POST body for creating a BigCommerce order shipment
// Wire this as the JSON body for the createShipment query
{
  "tracking_number": "{{ trackingNumberInput.value }}",
  "shipping_method": "{{ carrierSelect.value }}",
  "shipping_provider": "",
  "comments": "{{ shipmentNotesInput.value || '' }}",
  "order_address_id": "{{ orderShippingAddressQuery.data[0]?.id }}",
  "items": {{ JSON.parse('[' + orderProductsQuery.data.map(p => JSON.stringify({order_product_id: p.id, quantity: p.quantity})).join(',') + ']') }}
}
```

**Expected result:** Selecting an order in the main table loads a detail panel showing line items, shipping address, and payment method. The status update selector changes the order status in BigCommerce. The 'Mark Shipped' button creates a shipment record with tracking information.

### 4. Build the product and inventory management panel

Create queries for BigCommerce's v3 Catalog API to list and update products. Create a product list query:
- Method: GET
- Path: /v3/catalog/products
- URL parameters:
  - include: variants,images (to get variant inventory alongside product data)
  - inventory_level:less_than: {{ lowStockThreshold.value || 10 }} (optional filter)
  - keyword: {{ productSearchInput.value || '' }}
  - limit: 50
  - page: {{ productPagination.page || 1 }}

The v3 catalog response wraps products in a data array with a meta.pagination object for cursor-based pagination. Add a transformer to flatten the response and calculate total inventory across all variants.

Create an inventory update query:
- Method: PUT
- Path: /v3/catalog/products/{{ productsTable.selectedRow.id }}
- Body: { "inventory_level": {{ inventoryInput.value }}, "inventory_tracking": "product" }

For variant-level inventory (products with options like size/color), use:
- Method: PUT
- Path: /v3/catalog/products/{{ productsTable.selectedRow.id }}/variants/{{ variantsTable.selectedRow.id }}
- Body: { "inventory_level": {{ variantInventoryInput.value }} }

Drag a Table component for products and a nested Table for variants (visible when a product with variants is selected). Add an inline Number Input for quick inventory editing and a Save button that triggers the update query.

```
// Transformer for BigCommerce v3 Catalog products response
// data.data is the products array; data.meta.pagination has page info
const products = data.data || [];
return products.map(product => {
  const variants = product.variants || [];
  const totalInventory = product.inventory_tracking === 'product'
    ? (product.inventory_level || 0)
    : variants.reduce((sum, v) => sum + (v.inventory_level || 0), 0);
  const lowStock = totalInventory <= 10 && product.inventory_tracking !== 'none';
  return {
    id: product.id,
    name: product.name,
    sku: product.sku,
    price: parseFloat(product.price || 0).toFixed(2),
    cost_price: parseFloat(product.cost_price || 0).toFixed(2),
    inventory_level: totalInventory,
    inventory_tracking: product.inventory_tracking || 'none',
    low_stock: lowStock ? 'Yes' : '',
    variant_count: variants.length,
    status: product.availability,
    type: product.type,
    weight: product.weight,
    brand_id: product.brand_id
  };
});
```

**Expected result:** A product table shows all catalog items with inventory levels, low-stock indicators, and variant counts. Inline editing allows updating inventory quantities directly from the table. A nested variants table appears when a product with multiple variants is selected.

### 5. Add customer search and build the full dashboard layout

Add customer lookup functionality using BigCommerce's v2 Customers API. Create a customer search query:
- Method: GET
- Path: /v2/customers
- URL parameters:
  - email: {{ customerSearchInput.value }} (exact email match)
  - OR use /v3/customers with filter[email:like]: {{ customerSearchInput.value }}
  - limit: 25

The v3 customers endpoint supports more filter options including partial name matching. Create a query for customer order history:
- Method: GET
- Path: /v2/orders
- URL parameter: customer_id → {{ customersTable.selectedRow.id }}

And a store credit query:
- Method: GET
- Path: /v2/customers/{{ customersTable.selectedRow.id }}/storecredit

Organize the complete dashboard using a Tabs component with three tabs:
1. Orders — the order fulfillment table from step 2-3
2. Products — the product and inventory panel from step 4
3. Customers — the customer search and service panel

Add a dashboard header row with Statistic components showing real-time metrics:
- Pending orders count (query /v2/orders with status_id=1, return total from headers)
- Today's revenue (sum of today's completed order totals from orders query)
- Low stock alerts (count of products below threshold from products query)
- Orders awaiting fulfillment (count with status_id=3)

For complex multi-channel BigCommerce deployments with custom catalog management, order routing workflows, and ERP integrations, RapidDev's team can help architect and build your Retool solution.

```
// Customer transformer for BigCommerce v3 /customers response
const customers = data.data || [];
return customers.map(c => ({
  id: c.id,
  full_name: `${c.first_name || ''} ${c.last_name || ''}`.trim(),
  email: c.email,
  phone: c.phone || '',
  company: c.company || '',
  customer_group_id: c.customer_group_id,
  date_created: c.date_created
    ? new Date(c.date_created).toLocaleDateString()
    : '',
  store_credit: c.store_credit_amounts?.length
    ? '$' + parseFloat(c.store_credit_amounts[0]?.amount || 0).toFixed(2)
    : '$0.00',
  total_orders: c.orders_count || 0,
  notes: c.notes || '',
  accepts_marketing: c.accepts_product_review_abandoned_cart_emails ? 'Yes' : 'No'
}));
```

**Expected result:** A three-tab dashboard provides full order management, product inventory control, and customer service capability. The header statistics update based on live BigCommerce data. Operations teams can manage the entire store from the Retool panel without accessing the BigCommerce control panel.

## Best practices

- Store your BigCommerce access token as a secret configuration variable in Retool Settings → Configuration Variables — set it as the X-Auth-Token header value to avoid hardcoding credentials in the resource settings
- Create API accounts with the minimum required scopes — a read-only monitoring dashboard needs only Read scopes; write operations require Read-write scopes for the specific resources involved
- Use BigCommerce's v3 API endpoints where available (catalog, channels, customers) as they support better filtering, include more fields, and use cursor-based pagination — fall back to v2 only for endpoints not yet migrated (order shipments, store credit)
- Implement pagination properly — v2 orders use page/limit parameters, v3 catalog uses cursor-based pagination via meta.pagination; add 'Load more' or page controls to avoid loading all records at once for large stores
- Add confirmation dialogs for order status changes and inventory updates — these write operations affect the live storefront and cannot be easily undone for completed orders
- Use BigCommerce's include parameter in catalog queries (include=variants,images) to reduce the number of API calls needed to display full product data — avoid making separate per-product variant queries in a loop
- For Retool Cloud, whitelist Retool's IP ranges in any BigCommerce firewall or IP restriction settings if your store has additional API access restrictions configured

## Use cases

### Build an order fulfillment operations panel

Create a Retool app where your fulfillment team views all pending, processing, and shipped orders with filters by date range, status, and channel. Add one-click status update buttons, a bulk status change tool for updating multiple orders simultaneously, and a shipment tracking input that marks an order as shipped and records the tracking number. Include customer lookup from the order row to see full customer history.

Prompt example:

```
Build an order fulfillment dashboard with status filters (Pending, Awaiting Fulfillment, Shipped, Completed, Cancelled) and a date range picker. Display orders in a table with order number, customer name, total, item count, and status. Add a bulk action toolbar that lets staff select multiple orders and change their status simultaneously. Include a 'Mark Shipped' button that opens a modal for entering carrier and tracking number, then updates the order in BigCommerce.
```

### Build a product inventory management panel

Create a Retool panel for managing BigCommerce product inventory — view all products with current stock levels, identify low-stock items below a threshold, bulk update inventory quantities across variants, and track products pending restock. Add a price update tool that lets merchandising managers adjust prices for a selected product or category without going through the BigCommerce product editor.

Prompt example:

```
Build a product inventory panel with a low-stock alert table showing all products where inventory_level is below a configurable threshold (default 10). Display product name, SKU, current inventory, and price. Add an 'Update Stock' inline edit that saves new inventory quantities directly to BigCommerce via the Catalog API. Include a price editor that allows changing a product's price with a changelog entry stored in the internal price_changes database table.
```

### Build a customer service lookup tool

Create a Retool customer service panel that lets support agents search BigCommerce customers by name, email, or phone number, view their full order history with totals and statuses, and see their store credit balance and group membership. Add the ability to apply store credit adjustments and update customer group assignments directly from the panel.

Prompt example:

```
Build a customer service tool with a search bar that queries BigCommerce customers by email or name. When a customer is found, display their profile (name, email, phone, customer group, registration date) alongside their order history table showing order number, date, total, and status. Add a Store Credit panel showing current balance with an Add Credit button that opens a form for entering credit amount and a reason note logged to the internal credit_log table.
```

## Troubleshooting

### All API requests return 401 Unauthorized

Cause: The X-Auth-Token header value is incorrect or the API account was deleted or regenerated in BigCommerce's control panel.

Solution: Verify the X-Auth-Token header in the Retool resource settings matches your current access token from BigCommerce's API Accounts page. If you suspect the token has been regenerated, create a new API account in BigCommerce Control Panel → Advanced Settings → API Accounts and update the Retool configuration variable with the new access token. Note that regenerating an API account invalidates the previous access token immediately.

### API returns 403 Forbidden for specific endpoints

Cause: The API account's OAuth scopes don't include permission for the resource you're trying to access. For example, querying /v3/catalog/products requires the Products scope; managing customers requires the Customers scope.

Solution: In BigCommerce Control Panel → Advanced Settings → API Accounts, find your API account and click Edit. Expand the OAuth Scopes section and add the required scopes for the operations you're attempting. Save the account — the existing access token remains valid but now has the additional permissions. You don't need to create a new API account or update Retool credentials when adding scopes to an existing account.

### Date range filter parameters are not working or return all orders

Cause: BigCommerce's v2 Orders API expects dates in RFC 2822 format (Mon, 01 Jan 2024 00:00:00 +0000) but Retool date pickers typically output ISO 8601 format (2024-01-01T00:00:00Z) — these formats are not interchangeable.

Solution: Add a JavaScript transformer on the date values to convert Retool's date picker output to RFC 2822 format. In the query's URL parameters, use a JavaScript expression to format the date: {{ new Date(dateRange.start).toUTCString() }} which produces the RFC 2822 format BigCommerce expects. Test with a static date string first to confirm the format before wiring to a date picker component.

```
// Convert ISO date to RFC 2822 for BigCommerce v2 API
// Use in URL parameter value field
{{ new Date(dateRangePicker.start).toUTCString() }}
// Example output: Mon, 01 Jan 2024 00:00:00 GMT
```

### Product inventory updates succeed but inventory doesn't change in BigCommerce

Cause: The product's inventory_tracking setting is 'none' or 'variant' — updating the product-level inventory_level field has no effect when tracking is set to 'variant', and inventory_level is ignored when tracking is 'none'.

Solution: Check the inventory_tracking field in the product transformer output. If tracking is 'variant', update inventory at the variant level via PUT /v3/catalog/products/{id}/variants/{variant_id} instead of the product level. If tracking is 'none', first update the product to set inventory_tracking to 'product' or 'variant' before setting inventory levels.

## Frequently asked questions

### Does BigCommerce have a native Retool connector?

No. BigCommerce does not have a native connector in Retool's Resources catalog. You connect via a REST API Resource using the X-Auth-Token header for authentication. This approach provides full access to BigCommerce's v2 and v3 REST APIs, which cover all major commerce operations including orders, products, customers, coupons, channels, and store configuration.

### What is the difference between BigCommerce's v2 and v3 APIs, and which should I use in Retool?

BigCommerce's v2 API is the older interface covering orders, customers (partially), coupons, and shipments — it uses page-based pagination and some inconsistent response formats. The v3 API is the newer standard covering catalog (products, variants, categories), channels, carts, checkouts, and customer addresses — it uses cursor-based pagination and more consistent JSON structures. For new Retool integrations, prefer v3 endpoints where they exist (catalog operations, customer management) and use v2 only for resources not yet migrated to v3 (order shipments, store credit).

### How do I handle BigCommerce's rate limits in Retool?

BigCommerce enforces rate limits based on your plan — Enterprise plans have higher limits. The API returns X-Rate-Limit-Requests-Left and X-Rate-Limit-Time-Reset-Ms headers with each response. In Retool, add query caching for read-heavy queries (60-second cache for product and customer lists) to reduce API call frequency. For bulk operations, implement batching with delays using Retool Workflows rather than firing many requests simultaneously from the UI.

### Can I manage BigCommerce multi-storefront channels from Retool?

Yes. BigCommerce's v3 Channels API (/v3/channels) lists all storefront channels associated with your account. Order queries can be filtered by channel_id. You can build a channel selector in your Retool dashboard that filters orders and products by the selected channel, enabling a unified multi-storefront operations view. Channel configuration (updating site URLs, status) can also be managed via PUT /v3/channels/{channel_id}.

### How do I connect Retool to BigCommerce's webhook system for real-time updates?

BigCommerce webhooks send POST requests to a configured endpoint when events occur (order created, product updated, etc.). To receive these in Retool, create a Retool Workflow with a Webhook trigger — Retool provides a unique webhook URL. Configure a BigCommerce webhook (POST /v3/hooks) pointing to your Retool Workflow URL. The Workflow can then process the event, store data in your database, and trigger notifications. This gives near-real-time event data without polling the BigCommerce API continuously.

---

Source: https://www.rapidevelopers.com/retool-integrations/bigcommerce
© RapidDev — https://www.rapidevelopers.com/retool-integrations/bigcommerce