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 \
--jsonResponse
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.setupTokenholds a secret. Show it to the person only; never log or store it. The CLI hides secrets unless you pass--show-secrets.
Path parameters
| Name | Type | Description |
|---|---|---|
companyId | string (uuid) | Your workspace id, from productmetrics whoami or properties.list (company_id). |
Headers
| Name | Type | Required | Description |
|---|---|---|---|
Idempotency-Key | string (uuid) | No | A new UUID per intended change, the same one to retry it: a retry with the same key does not repeat the change. |
Body
| Name | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | The store platform. It decides what else the body needs and what the answer holds (see above). One of shopify, shopware6, woocommerce, lightspeed_c_series. |
requestKey | string (uuid) | No | A UUID that makes a retry safe, instead of the Idempotency-Key header. |
storeUrl | string (uri) | No | The https root of the store, for woocommerce and shopware6. |
predecessorEcommerceConnectionId | string (uuid) | No | The connection this one replaces, when reconnecting a store. |
cluster | enum | No | lightspeed_c_series only: the Lightspeed cluster, from the person’s Lightspeed back office. One of eu, us. |
shopDomain | string | No | lightspeed_c_series only: the shop’s domain, from the Lightspeed back office. Up to 253 characters. |
shopId | string | No | lightspeed_c_series only: the shop id, from the Lightspeed back office. 1 to 100 characters. |
apiKey | string | No | lightspeed_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. |
apiSecret | string | No | lightspeed_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"
}| Status | Code | When |
|---|---|---|
| 400 | invalid_request | A path, query or body value does not match this page. details.issues lists each location, path and message. |
| 401 | invalid_token | The token is missing, expired or revoked: sign in again (productmetrics login). The WWW-Authenticate header says why. |
| 402 | subscription_required | The workspace has no Pro plan. |
| 403 | insufficient_scope | The token lacks the setup scope (details.required_scope): sign in again and allow it. |
| 404 | not_found | An id in the path does not exist, or the signed-in person cannot open it. |
| 429 | rate_limited | More than 600 requests a minute for this person: wait the Retry-After seconds (60) and retry. |