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

CTP_PROJECT_KEY=your-project-key
CTP_CLIENT_ID=your_client_id
CTP_CLIENT_SECRET=your_client_secret
CTP_AUTH_URL=https://auth.europe-west1.gcp.commercetools.com
CTP_API_URL=https://api.europe-west1.gcp.commercetools.com

# A long random string. commercetools sends it back on every call as
# "Authorization: Bearer <secret>"; the connector rejects anything else.
#   openssl rand -hex 32
EXTENSION_SHARED_SECRET=your_long_random_shared_secret

APP_CALLBACK_URL=https://your-connector.example.com/extension
PORT=3012

# Optional — commercetools has no native weight or tag fields, so the
# connector reads them from these product-variant attributes.
WEIGHT_ATTRIBUTE=weight
TAGS_ATTRIBUTE=shiprate_tags
NAME_LOCALE=en

npm install
node src/scripts/register.js   # creates the custom Type + API Extension
npm start

The register.js script provisions the two commercetools resources the connector relies on. Run it once per project, or again after the callback URL changes — re-running is safe, as existing resources are updated in place rather than duplicated.

Both names are fixed in src/lib/constants.js and must match between the registration script and the running service.

Unlike Shopify and BigCommerce, commercetools does not HMAC-sign extension requests. Instead the extension is registered with an AuthorizationHeader destination, so commercetools sends a fixed header on every call:

Authorization: Bearer <EXTENSION_SHARED_SECRET>

The connector compares that header against its own EXTENSION_SHARED_SECRET using a constant-time comparison and rejects any mismatch with a 401. The same check guards both /extension and /rates. npm run register writes the secret into the extension destination for you, so the two sides always agree.

When a cart is created or updated, commercetools calls the API Extension. The connector resolves the destination and line items, requests rates from ShipRateAPI, and returns an update action that writes the quotes onto the cart as a JSON-encoded string in the shipRateApiQuotes custom field. If the cart already carries the ship-rate-api Type the connector patches that single field (setCustomField); otherwise it assigns the Type and seeds the field (setCustomType), so custom fields belonging to other Types are never clobbered. Carts with no shipping country or no line items are skipped.

Both quote paths emit the same objects — the value of shipRateApiQuotes is this array, JSON-encoded as a string, so remember to JSON.parse() it:

{
  "carrierCode":     "dpd_uk",
  "carrierName":     "DPD UK",
  "methodCode":      "dpd_uk_express_delivery",
  "methodName":      "Express Delivery",
  "label":           "DPD UK - Express Delivery",
  "amount":          5.99,   // decimal, matches the cart currency
  "centAmount":      599,    // minor units — build a commercetools money object
  "currency":        "GBP",
  "minDeliveryDays": 1,
  "maxDeliveryDays": 2
}

commercetools tags are driven by product attributes. Add a shiprate_tags attribute (type text) to the relevant product types, then set a comma-separated value on each product you want to route — e.g. fragile, cold-storage. The connector reads this attribute from each line item’s product and forwards the tags in the rate request. See Tags & Routing for the full list of recognised tags and their routing behaviour.