BigCommerce

Developer Guide
Overview

The ShipRateAPI BigCommerce app registers as a Real-Time Shipping Quoteprovider. BigCommerce sends a rate request to the app's callback URL at checkout; the app verifies the request, proxies it to the ShipRateAPI API, and returns the rates in the format BigCommerce expects.

  • BigCommerce store with a plan that supports Real-Time Shipping Quotes (Plus or higher)
  • Node.js 18+ runtime
  • A publicly accessible HTTPS callback URL
Environment variables

Copy .env.example to .env and fill in the values:

SHIPRATE_API_ENDPOINT=https://api.shiprateapi.com/api/v1/quotes
SHIPRATE_API_KEY=sk_live_xxxxxxxxxxxxxxxxxxxx

BIGCOMMERCE_CLIENT_SECRET=your_bc_client_secret
BC_STORE_HASH=your_store_hash
BC_ACCESS_TOKEN=your_bc_access_token

APP_CALLBACK_URL=https://your-app.example.com/rates
PORT=3011
VariableDescription
SHIPRATE_API_ENDPOINTShipRateAPI quotes endpoint — https://api.shiprateapi.com/api/v1/quotes. Update the version path here without a code change. The app sends X-Platform: bigcommerce automatically.
SHIPRATE_API_KEYYour ShipRateAPI API key for this store
BIGCOMMERCE_CLIENT_SECRETUsed to verify the HMAC signature on inbound requests
BC_STORE_HASHYour BigCommerce store hash — visible in the store URL and API paths
BC_ACCESS_TOKENBigCommerce API token with store/shipping_zones scope
APP_CALLBACK_URLPublic HTTPS URL registered as the shipping provider endpoint in BigCommerce
Installation & registration
npm install
node src/scripts/register.js   # registers the shipping provider with BigCommerce
npm start

The register.js script calls the BigCommerce Shipping Zones API to create a Real-Time Shipping provider entry pointing at your APP_CALLBACK_URL/rates. Run it once per store, or again after changing the callback URL.

You can verify the provider is registered in your BigCommerce control panel under Store Setup → Shipping → Shipping Methods. ShipRateAPI should appear as a custom provider in the list.

Request verification

Each inbound request from BigCommerce is verified using HMAC-SHA256 with your BIGCOMMERCE_CLIENT_SECRET before the payload is forwarded to the ShipRateAPI API. Invalid requests receive a 401 response.

Tip: BigCommerce sends the signature in the X-BC-Webhook-Signature header for webhook events, and as a query parameter for Real-Time Shipping provider callbacks. The middleware handles both.

Product tags

BigCommerce does not have a native product tags field equivalent to Shopify. To assign ShipRateAPI routing tags to BigCommerce products, use Product Custom Fields: create a custom field named shiprate_tags on any product and set the value to a comma-separated list of tags (e.g. fragile, cold-storage). The app reads this custom field from the product data and forwards the tags in the rate request.