BigCommerce

Sync customer and product data from your warehouse to BigCommerce. Keep your BigCommerce store records enriched with the latest data from your data warehouse using the BigCommerce REST Management API v3.

Prerequisites

• A BigCommerce store (Standard, Plus, Pro, or Enterprise plan)
• An API account created in the BigCommerce control panel with an access token
• The API account must have the following OAuth scopes:
  • Customers: modify scope for /customers
  • Products: modify scope for /catalog/products (if syncing products)

Authentication

API Access Token

1. In your BigCommerce control panel, go to Settings > API > API accounts
2. Click Create API Account > Create V2/V3 API Token
3. Give the account a name (e.g., “Zeotap Integration”)
4. Under OAuth Scopes, set the following:
   • Customers: modify
   • Products (if needed): modify
   • Store Information: read-only (used for connection testing)
5. Click Save
6. Copy the Access Token, Client ID, and Store Hash from the confirmation dialog
7. Paste the Access Token into the Access Token field in Zeotap
8. Paste the Store Hash into the Store Hash field in Zeotap

Important: The access token is only shown once when you create the API account. Store it securely. If you lose it, you must create a new API account to generate a new token.

Configuration

Target Settings

Supported Operations

Sync Modes

Audience Sync Modes

BigCommerce does not have a native list or segment membership API, so audience sync modes are not supported. Use standard sync modes to create or update customer and product records.

Features

• Field Mapping: Yes
• Schema Introspection: No

Required Mapping Fields

Default Destination Fields

Customer Fields

Product Fields

How It Works

1. Customer Sync (Batch): Zeotap sends customers in batches of up to 10 records per API call using the BigCommerce v3 Customers endpoint. For insert mode, customers are created via POST /v3/customers. For update and upsert modes, customers are sent via PUT /v3/customers, which performs an upsert — updating existing records matched by ID and creating new ones if no match is found.

2. Product Sync (Individual): Products are synced one at a time using the Catalog Products endpoint. For insert mode, products are created via POST /v3/catalog/products. For update mode, products are updated via PUT /v3/catalog/products/{id}. Upsert mode updates by product ID if available, otherwise creates a new product.

3. Error Handling: Each batch (for customers) or individual request (for products) is processed independently. Failed rows are reported with specific error messages from the BigCommerce API. Transient errors (rate limits, server errors) are retried with exponential backoff.

4. Primary Key Handling: For update and upsert modes, the primary key should be the BigCommerce record ID (numeric). For customers, this is the customer ID. For products, this is the product ID.

Rate Limits

BigCommerce uses a request-based rate limiting system:

Additional limits:

• Maximum 400 concurrent requests per store
• Maximum 10 customers per batch request
• Products are synced individually (1 per request)

Zeotap automatically handles rate limiting with exponential backoff when the API returns 429 (Too Many Requests) responses.

Best Practices

• Use customer batch operations to minimize API calls — Zeotap automatically batches customers in groups of 10
• Map only required fields plus any fields you need to update to reduce payload size
• Use upsert mode for customers to avoid duplicate records — BigCommerce matches by customer ID on PUT requests
• Schedule syncs during off-peak hours if you are on a Standard or Plus plan to avoid rate limit contention with other integrations
• Set the product type correctly — use physical for tangible goods and digital for downloadable products
• Include weight for physical products — BigCommerce requires a weight value for physical products, even if it is 0

Troubleshooting

Authentication failed: invalid or expired access token

Verify the API access token in your BigCommerce API account settings. If the token was regenerated or the API account was deleted, you must create a new API account and update the token in Zeotap.

Store not found (404)

Verify the store hash is correct. You can find it in Settings > API > API accounts or in the URL when accessing your store’s API. The store hash is the alphanumeric string in the API path (e.g., abc123def in api.bigcommerce.com/stores/abc123def/v3/).

Customer email already exists

BigCommerce requires unique email addresses for customers. When using insert mode, you may get duplicate email errors. Switch to upsert mode to update existing customers with the same email address, or ensure your source data contains only unique email addresses.

Missing required fields for customer creation

Customer creation requires email, first_name, and last_name. Verify these fields are mapped in your field mapping. All three must have non-empty values.

Missing required fields for product creation

Product creation requires name, type, weight, and price. For physical products, weight must be a numeric value (can be 0). The type field must be either physical or digital.

Rate limiting (429 errors)

Zeotap automatically retries rate-limited requests with exponential backoff. If you see persistent rate limit errors, consider reducing sync frequency or spacing out syncs. Check your BigCommerce plan’s rate limit quotas and ensure other integrations are not consuming excessive API capacity.

Product update returns 404

When using update or upsert mode for products, the primary key must be a valid BigCommerce product ID. Verify the product exists in your BigCommerce store and that the primary key column in your source data contains valid numeric product IDs.

Insufficient API scopes

If API calls fail with permission errors, verify your API account has the correct OAuth scopes: modify for Customers and/or Products. You may need to create a new API account with the correct scopes, as BigCommerce does not allow editing scopes on existing accounts.