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_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
# Rate display + labels.
# RATE_DISPLAY grouped (default) = one carrier heading per carrier; flat = single group.
# RATE_LABEL_FORMAT tokens {Carrier} {Service} (case-insensitive) — used in flat mode.
# RATE_CARRIER_NAME heading for the single group in flat mode.
RATE_DISPLAY=grouped
RATE_LABEL_FORMAT={Carrier} - {Service}
RATE_CARRIER_NAME=ShipRateAPI| Variable | Description |
|---|---|
SHIPRATE_API_ENDPOINT | ShipRateAPI 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_KEY | Your ShipRateAPI API key for this store |
BIGCOMMERCE_CLIENT_SECRET | Required in production. Used to verify the HMAC signature on inbound requests — see Request verification below. If it is unset the connector skips verification entirely. |
BC_STORE_HASH | Your BigCommerce store hash — visible in the store URL and API paths |
BC_ACCESS_TOKEN | Store-level BigCommerce API token with the Information & Settings write scope (used only by the registration script) |
APP_CALLBACK_URL | Public HTTPS URL registered as the shipping provider endpoint in BigCommerce. Registered verbatim, so it must include the /rates path — the script rejects non-HTTPS URLs. |
RATE_DISPLAY | Optional (default grouped). grouped gives one carrier heading per carrier, with the service name as each option's label. flat puts every rate under a single heading with the carrier folded into each label. |
RATE_LABEL_FORMAT | Optional (default {Carrier} - {Service}). Template for each option's label when RATE_DISPLAY is flat. Tokens {Carrier} and {Service} (case-insensitive). |
RATE_CARRIER_NAME | Optional (default ShipRateAPI). Heading shown for the single group when RATE_DISPLAY is flat. |
Installation & registration
npm install
node src/scripts/register.js # registers the shipping provider with BigCommerce
npm startThe register.js script calls the BigCommerce Shipping Carrier API (POST /v2/shipping/carriers) to create a custom carrier named ShipRateAPI with the code nysa-shiprate. Run it once per store, or again after changing the callback URL.
The callback URL is registered verbatim. Whatever you set as APP_CALLBACK_URL is sent as the carrier's callback_urlwith no path appended — so it must already end in /rates, as it does in .env.example. Re-running the script is safe: if the carrier already exists BigCommerce returns a 409, which the script reports and treats as a no-op rather than an error.
You can verify the provider is registered in your BigCommerce control panel under Store Setup → Shipping → Shipping Methods, where you enable it for the shipping zones you want it to serve.
Request verification
When BIGCOMMERCE_CLIENT_SECRET is set, each inbound request is verified using HMAC-SHA256 before the payload is forwarded to the ShipRateAPI API. The middleware computes the HMAC of the raw request body with your client secret and compares it — using a constant-time comparison — against the lowercase hex digest in the X-BC-Signature header. A missing or invalid signature receives a 401 response.
Never run without BIGCOMMERCE_CLIENT_SECRET. If the variable is unset the connector logs a warning at startup and skips verification entirely — every request is accepted, leaving the endpoint open to anyone who finds the URL. This exists only as a local-development convenience. Always set it in production.
Product tags
Tag-based routing is not available on BigCommerce. BigCommerce does not include product tags or custom fields in its Real-Time Shipping Quotes callback, so the connector has no tag data to forward and always sends an empty tag list.
This means tag-routed rate tables will never match a BigCommerce request. Any rate table with requiredTags set is skipped for this platform, so make sure each zone you serve has at least one table with no tag restrictions — otherwise BigCommerce customers see no rates at all. Route using zones, weight, order value, or dimensions instead.