Identifying stores and customers

When a store owner completes the OAuth flow, EcartAPI redirects to your Redirect URL with the store's access token and metadata. This guide explains how to pass your own customer context through the flow and how to reliably map the resulting store to the right customer in your system.

Passing context with the state parameter

The OAuth URL accepts a state parameter (also accepted as origin on some flows) that EcartAPI passes through unchanged to your Redirect URL. Use it to carry whatever identifier you need — a user ID, session token, or tenant key — so you know who initiated the connection when the redirect arrives.

https://oauth.ecartapi.com/{APP_ID}?state={your_identifier}

The value appears in the redirect URL as the state query parameter:

https://yourapp.com/callback?access_token=...&state={your_identifier}&shop_id=...

Constraints:

• Maximum length: 255 characters
• Use URL-safe characters only (letters, digits, -, _, ., ~). Avoid spaces, &, =, or other characters that could break URL parsing.

Parameters returned in the redirect

EcartAPI returns a standardized set of parameters regardless of the connected platform. Do not expect to find platform-specific fields such as customerId, owner, storeReference, marketplace, or any other identifier native to a particular ecommerce. All values in the redirect are EcartAPI's own unified fields.

Recommended approach: use shop_id

shop_id is the most reliable way to identify a store in your system. EcartAPI assigns it when the store is first connected and it does not change when the store is reconnected.

Typical implementation:

1. Generate a unique identifier for your customer (e.g. user_123) and pass it as state in the OAuth URL.
2. On redirect, read state to know which of your customers connected a store.
3. Save shop_id as the key linking that customer to their store in your database.
4. When the store reconnects (new access_token), match by shop_id and update the token — the shop_id stays the same.

OAuth URL → ?state=user_123
            ↓
Redirect   → ?state=user_123&shop_id=abc456&access_token=new_token
            ↓
Your DB    → UPDATE stores SET access_token = 'new_token' WHERE shop_id = 'abc456'

Store reconnections and token rotation

There are no webhooks for store connection or disconnection events. To detect that a store has disconnected, watch for 401 errors with ecartapiError: false when calling the API — that means the platform rejected the token and the store owner needs to reconnect.

When a store reconnects, the redirect fires again with the same shop_id but a new access_token. Always overwrite the stored token on reconnection.

Multiple marketplaces (Amazon)

Amazon treats each marketplace (US, UK, DE, MX, etc.) as a separate store. Each marketplace requires its own EcartAPI integration — a separate OAuth flow. Each integration returns its own shop_id and access_token. Your system needs to store all of them if you serve merchants across multiple Amazon marketplaces.

Next

→ OAuth 2.0 — Full OAuth flow reference.
→ Store authentication — Redirect parameters and ecartapi_key validation.
→ Error codes and token expiration — How to detect expired tokens and prompt reconnection.