← Back to EcomCentral
COMMERCEHQ REST API v1

CommerceHQ Setup Guide

Connect your CommerceHQ store to EcomCentral using HTTP Basic authentication with your API key and password.

Prerequisites

ℹ️ CommerceHQ uses HTTP Basic authentication. Your API key and password are base64-encoded as {api_key}:{api_password} and sent in the Authorization header with every request. No OAuth flow is required.

Getting Your API Credentials

  1. Log in to your CommerceHQ store admin panel
  2. Go to Settings → API (or Apps → Private Apps)
  3. Click Create API credentials or Generate new key
  4. Enable at least Orders (read + write) and Products (read + write) scopes
  5. Copy the generated API Key and API Password
  6. Note your store domain from the address bar, e.g. mystore.commercehq.com
  7. In EcomCentral, add a new CommerceHQ connection with all three values
  8. Click ⚡ Test — a successful response confirms your credentials are correct

Credentials Reference

KeyRequiredDescriptionExample
shop_url Required Full store domain (with or without https:// prefix) mystore.commercehq.com
api_key Required API Key from Settings → API credentials abc123key…
api_password Required API Password paired with the API Key secret456pass…
✅ Alternative key names accepted: shopUrl or url for the shop URL; apiKey or key for the API key; apiPassword or password for the API password.

API Endpoints Used

OperationMethodEndpoint
Test connectionGET/api/v1/orders?page=1&per_page=1
List ordersGET/api/v1/orders?page=P&per_page=N&sort=-created_at
Order detailGET/api/v1/orders/{id}
Add tracking (fulfillment)POST/api/v1/orders/{id}/fulfillments
List productsGET/api/v1/products?page=P&per_page=N
Product detailGET/api/v1/products/{id}
Update variant stockPUT/api/v1/variants/{id} with { variant: { inventory_quantity: N } }
ℹ️ All list endpoints return a consistent envelope: { orders/products: [...], meta: { pagination: { total, per_page, current_page } } }. EcomCentral uses meta.pagination.total for page count display.

Supported Features

FeatureSupportedNotes
View orders (paginated)✅Order number, date, status, total + currency; sorted newest first
View order detail✅Customer info, billing address, shipping address, line items, financial status, tax
Add tracking (fulfillment)✅Tracking number + company + URL; automatically includes all line items
View products (paginated)✅First variant SKU, price, and inventory quantity
View product detail + variants✅All variants with ID, SKU, price, stock, options; first image thumbnail
Update stock quantity✅PUT /api/v1/variants/{id} — stock is updated per variant ID
Test connection✅Verifies credentials by fetching the first page of orders
⚠️ Stock is updated per variant, not per product. You need the numeric Variant ID (visible in the product detail panel) to update inventory — not the product ID or SKU. Each variant tracks its own inventory_quantity.

Troubleshooting

✕ 401 Unauthorized

The api_key or api_password is incorrect. Regenerate your API credentials in Settings → API and update the connection in EcomCentral. Make sure there are no extra spaces around the values.

✕ Connection error / could not resolve host

Check that shop_url is your correct store domain (e.g. mystore.commercehq.com). Do not include a trailing slash or a path — EcomCentral automatically adds the https:// prefix and /api/v1 base path.

✕ Fulfillment creation fails

Ensure your API credentials have write access to Orders. Read-only API scopes cannot create fulfillments. Also confirm the order is in a fulfillable state (not already fully fulfilled or cancelled).

✕ Stock update has no effect

Verify you are using the correct Variant ID (the numeric ID shown in the variants table in the product detail panel), not the product ID or SKU. Each CommerceHQ variant has its own ID and independent inventory count.