Skip to content
Stores and tracking

Connect a store

Starts connecting a store to the workspace so its orders are tracked.

POST /companies/{companyId}/stores

Scope setup · Access Changes data · Operation id stores.connect

Try it

productmetrics runs after productmetrics login; curl needs PM_TOKEN (see Authentication). Set $COMPANY_ID first.

productmetrics stores connect \
  --company-id $COMPANY_ID \
  --provider shopify \
  --auto-idempotency-key \
  --json

Response

API response (200):

{
  "data": {
    "mode": "redirect",
    "authorizationUrl": "https://example-store.com"
  },
  "request_id": "req_01J1HACKN008Y0HJQ19FZRZBS8"
}

CLI output: productmetrics stores connect --json prints { "ok": true, "data": …, "request_id": "…" } with the same data, plus "next_action": { "type": "browser", "url": "…" } when a person must open a link, or "next_action": { "type": "store_plugin", "expires_at": "…" } while the store waits for its setup token in the plugin (exit code 4).

Before you call

Needs editor or admin access; every platform but Shopify also needs Pro. Send an Idempotency-Key header (a UUID) or requestKey, so a retry does not start a second connection. What happens next depends on provider: shopify answers mode: redirect with an authorizationUrl the person must open and approve in Shopify Admin. woocommerce and shopware6 (storeUrl: the https store root) answer mode: plugin_claim with a one-time claim.setupToken the person pastes into the Product Metrics plugin they install in their store admin before claim.expiresAt. The token is a secret hidden from you: tell the person to take it from the Product Metrics app. lightspeed_c_series needs cluster, shopDomain, shopId, apiKey and apiSecret from the person’s Lightspeed back office and answers mode: provisioning; apiKey and apiSecret are credentials: ask the person for them, never invent, guess or reuse them, and never repeat them back. Afterwards call tracking.get_commerce_configuration to see the connection become active.

Browser step: the result can hold a URL the person must open in a browser. An agent cannot finish that step itself: give the person the URL (the CLI prints it and exits 4).

Secret: claim.setupToken holds a secret. Show it to the person only; never log or store it. The CLI hides secrets unless you pass --show-secrets.

Path parameters

NameTypeDescription
companyIdstring (uuid)Your workspace id, from productmetrics whoami or properties.list (company_id).

Headers

NameTypeRequiredDescription
Idempotency-Keystring (uuid)NoA new UUID per intended change, the same one to retry it: a retry with the same key does not repeat the change.

Body

NameTypeRequiredDescription
providerstringYesThe store platform. It decides what else the body needs and what the answer holds (see above). One of shopify, shopware6, woocommerce, lightspeed_c_series.
requestKeystring (uuid)NoA UUID that makes a retry safe, instead of the Idempotency-Key header.
storeUrlstring (uri)NoThe https root of the store, for woocommerce and shopware6.
predecessorEcommerceConnectionIdstring (uuid)NoThe connection this one replaces, when reconnecting a store.
clusterenumNolightspeed_c_series only: the Lightspeed cluster, from the person’s Lightspeed back office. One of eu, us.
shopDomainstringNolightspeed_c_series only: the shop’s domain, from the Lightspeed back office. Up to 253 characters.
shopIdstringNolightspeed_c_series only: the shop id, from the Lightspeed back office. 1 to 100 characters.
apiKeystringNolightspeed_c_series only: the API key from the Lightspeed back office. A credential: ask the person, never invent or repeat it. 1 to 500 characters.
apiSecretstringNolightspeed_c_series only: the API secret from the Lightspeed back office. A credential: ask the person, never invent or repeat it. 1 to 500 characters.

Errors

A failure answers with its HTTP status and { error: { code, message, details? }, request_id }. Branch on code (stable, lower_snake); show message to the person. The CLI prints the same error with "ok": false.

{
  "error": {
    "code": "insufficient_scope",
    "message": "This operation needs the setup scope; connect again and allow it.",
    "details": {
      "required_scope": "setup"
    }
  },
  "request_id": "req_01J3QSGEHVHM6YFNK0N5FEZE9X"
}
StatusCodeWhen
400invalid_requestA path, query or body value does not match this page. details.issues lists each location, path and message.
401invalid_tokenThe token is missing, expired or revoked: sign in again (productmetrics login). The WWW-Authenticate header says why.
402subscription_requiredThe workspace has no Pro plan.
403insufficient_scopeThe token lacks the setup scope (details.required_scope): sign in again and allow it.
404not_foundAn id in the path does not exist, or the signed-in person cannot open it.
429rate_limitedMore than 600 requests a minute for this person: wait the Retry-After seconds (60) and retry.

All Stores and tracking operations