BigCommerce API Integration: A Practical Catalogue Sync Guide

Revision: revised API guidance, a read-only request example and a proposed catalogue synchronization design.

A BigCommerce integration needs an explicit data contract, not just working API credentials. Decide which system owns each field, how records correspond and what happens when requests fail. Those decisions determine whether a connection remains useful after the first successful transfer.

This guide designs a hypothetical integration between one BigCommerce store and an internal catalogue. The pilot updates selected content fields on already-mapped products. It reports unmapped records for review and leaves creation, deletion, prices, orders, payments and inventory outside its write scope. It is a planning example, not a deployed connector or a performance claim.

Choose the API surface and account deliberately

BigCommerce has management APIs for store administration and storefront APIs for shopper-facing applications. Access depends on the endpoint, authentication and granted permissions. Describing these as “a public API that exposes everything” and “a private API” misses those boundaries.

For the server-side catalogue pilot, use the REST Management Catalog API. BigCommerce's API account documentation distinguishes store-level accounts from app-level accounts used for app installations. A dedicated store-level account can suit a single-store integration. An application intended for installation by multiple merchants needs its own installation and authorization design.

Start the discovery request with Products read-only permission. The documented scope name is store_v2_products_read_only, including for the V3 Catalog API. Provision a separate credential with only the additional permissions required for an approved write phase. Keep tokens in protected server-side configuration, separated by environment, with an owner and a revocation procedure.

Stencil is BigCommerce's theme framework. It is not a backend synchronization service. Do not place management credentials in a theme, browser JavaScript or a public repository. A storefront redesign and a catalogue integration can be scoped separately.

Map identifiers and assign ownership before writing

Maintain a mapping from each internal product ID to its BigCommerce store and product ID. Map internal variants separately to the corresponding BigCommerce product and variant IDs. BigCommerce's catalogue model distinguishes products and variants; a parent product's SKU is not a complete variant inventory.

Use SKU values to help investigate an initial match, not as an assumption that identities will remain unchanged across systems. Missing values, changed codes or conflicting source rows require review. Store confirmed mappings and enforce uniqueness in your mapping table so one remote record cannot silently attach to two unrelated internal records.

Record how conflicting manual edits are handled. For this pilot, a difference in an internally owned field becomes a review item unless it belongs to an approved source-change batch. Coordinate a pause in manual editing of these fields during approved write batches. This pilot does not promise conflict-free simultaneous editing by both systems.

Make a small read-only request first

The following Bash example assumes BIGCOMMERCE_STORE_HASH and BIGCOMMERCE_ACCESS_TOKEN are already supplied through your local environment. Use a trusted development environment with shell tracing disabled. Do not print credentials or enable verbose HTTP logging.

set +x
: "${BIGCOMMERCE_STORE_HASH:?Set BIGCOMMERCE_STORE_HASH}"
: "${BIGCOMMERCE_ACCESS_TOKEN:?Set BIGCOMMERCE_ACCESS_TOKEN}"

curl --fail --silent --show-error \
  --connect-timeout 10 --max-time 30 \
  --get \
  --url "https://api.bigcommerce.com/stores/${BIGCOMMERCE_STORE_HASH}/v3/catalog/products" \
  --data-urlencode 'limit=2' \
  --data-urlencode 'page=1' \
  --data-urlencode 'include_fields=id,name,sku' \
  --header @- <<EOF
Accept: application/json
X-Auth-Token: ${BIGCOMMERCE_ACCESS_TOKEN}
EOF

This illustrative request has not been run against a live store for this article. It uses the List Products endpoint and prints its response. The header is passed through standard input so the token is not placed in curl's command-line arguments.

It requests at most two products from the first page, with a reduced field set. It is not a full catalogue export or a synchronization script. A complete comparison must handle pagination, fetch required variant records and distinguish a successful empty result from an error. Do not treat this small sample as proof that every mapping is correct.

Reconcile before enabling updates

Read the selected catalogue and import the observed state into a local comparison workspace without modifying the store. Record scan time, source revision and pagination progress. Compare the mapped records against the internal source and classify each as unchanged, proposed content update, unmapped, missing remotely or conflicting.

Catalogue data can change during a paginated scan. Do not infer that a record was deleted solely because it was absent from one incomplete pass. Check scan completion, re-read questionable records and reconcile changes that arrived during the scan.

Have the catalogue owner approve a small update batch. Save the intended field changes and before-values, then send only the permitted fields to the mapped product IDs. Re-read results and compare normalized values. An HTTP success establishes that a request succeeded; it does not replace checking the business result.

Use source revisions and a per-product operation record to reject obsolete queued work. A rollback must also consider later edits: restoring an old description blindly can erase a newer approved change. Pause conflicting products for review.

Treat webhooks as signals to reconcile

BigCommerce's webhook documentation describes lightweight callbacks, possible duplicate deliveries and retry behavior. Subscribe to the product events needed by the integration and verify their payloads against the event reference. A callback signals that work may be needed; it is not a complete product snapshot.

For this proposed receiver, verify a secret custom header configured when registering the webhook, validate the expected store and allowed event scope, durably record accepted work, then return HTTP 200 promptly. Use HTTPS and keep the callback secret separate from the management token. The payload's hash helps recognize duplicates; it is not an authentication signature.

Process accepted work asynchronously. Fetch the current product state, compare it with the approved ownership rules and update the local observation or raise a conflict. Events caused by your own writes should result in an unchanged comparison, not an endless write-back loop.

Use the callback hash, store and scope as short-lived duplicate hints, not a permanent record of unique business changes. Make the work safe to repeat; mark a product for another read when callbacks arrive during its job. Serialize reconciliation per product, re-read the latest source revision before writing and rerun if changes arrive during processing. Arrival order is not a safe replacement for current-state checks.

Check webhook activity and run a scheduled catalogue comparison as a recovery path. Agree how old unsynchronized data may become before alerting. A healthy callback endpoint alone does not prove that workers are processing their backlog.

Classify failures instead of retrying everything

BigCommerce's rate-limit guidance describes a store quota shared by its API clients and response headers for remaining capacity. Coordinate workers, spread requests over time and use the returned limits rather than assuming a fixed allowance.

For a 429 response, respect X-Rate-Limit-Time-Reset-Ms when present; its unit is milliseconds. Use bounded backoff with jitter when timing headers are unavailable or transient failures persist. Do not launch a fresh retry loop from every worker simultaneously.

Authentication failures need credential or permission investigation. Invalid field values need source correction. A missing product needs mapping review. For a timeout after a write, read the remote record before deciding whether to retry: the change may already have succeeded. Track outcomes per record when processing a batch.

After the agreed retry limit, retain failed work for an operator to inspect and replay safely. Log operation IDs, status, attempts and sanitized error details. Exclude tokens and unneeded payload content from logs.

Agree acceptance checks and ongoing ownership

Set measurable acceptance conditions for catalogue size, change volume, allowed lag and recovery time on an agreed test environment. Name the owner of alerts, mappings, credentials and source-data corrections. Include an operating guide and a way to pause writes without losing the review queue.

Use the software requirements template to document the contract. For broader scope, see our online-store planning guide. If you are evaluating another platform, our Shopify development guide covers its implementation decisions. Our e-commerce development page explains the project work we discuss with merchants.