Public API Scopes - What Each Permission Grants

Scopes

There are four data scopes, plus offline_access. All of them are read-only - there is no write scope in the MerchantFlow Public API, so an application can never modify a merchant's data.

Ask for the narrowest set that does your job. The merchant sees every scope you request, in plain language, before they approve. The Merchant sees lines below are the consent screen's wording, verbatim.

store:read

Store name, platform, shop domain, currency, timezone, when the store last synced, and how far back the merchant's plan lets you read.

Unlocks /api/v1/account and /api/v1/stores. Almost every integration wants this: /api/v1/account is how you confirm which store you are connected to and whether the data is fresh.

Merchant sees: Read your store details - "Store name, currency, timezone, and when your data was last synced."

orders:read

Orders and their full economics: revenue, discounts, tax, refunds, COGS, fulfilment cost, payment fees, allocated ad spend, contribution profit and net profit - plus line items, attribution (UTM, source, landing page) and the shipping country code.

Unlocks /api/v1/orders and /api/v1/orders/{id}.

It also includes customer_ref, a pseudonymous per-customer identifier that lets you tell a repeat buyer from a new one. It is not an email address and cannot be turned into one - see Data and privacy.

Merchant sees: Read your orders and their economics - "Revenue, COGS, fulfilment costs, fees, and profit per order. Includes a pseudonymous customer reference so the app can tell repeat buyers from new ones. It never receives customer names, email addresses, phone numbers, or shipping addresses."

That disclosure is deliberate and specific. If your product's own privacy copy says something different, the merchant will notice.

products:read

Products, their variants, and the current cost of goods sold for each.

Unlocks /api/v1/products and /api/v1/products/{id}.

Merchant sees: Read your products and costs - "Products, variants, and cost of goods sold."

profitability:read

The profit and loss waterfall - gross revenue through to net profit - as a period summary and as a daily series.

Unlocks /api/v1/profitability/summary and /api/v1/profitability/daily.

Independent of orders:read. A dashboard that only needs store-level profit does not need order access, and should not ask for it.

Merchant sees: Read your profit & loss - "Your P&L summary and daily profit history."

offline_access

Not a data permission. It is what makes MerchantFlow issue a refresh token, so your connection survives past the one-hour access token lifetime.

Without it the merchant has to repeat the browser consent flow every hour, which in practice means your integration appears to break. Request it unless you are building something genuinely one-shot.

Merchant sees: Stay connected - "Lets the app refresh its access without sending you back here every hour."

Below the scopes, every consent screen ends with: "Read-only. No customer names, email addresses, phone numbers, or shipping addresses are ever shared. You can disconnect this app at any time from Settings."

There is no "read everything" scope

MerchantFlow's MCP server has an mcp:read:all convenience scope, because an AI client cannot predict which of fifty tools a merchant will ask it to use. A partner integration knows exactly what it needs, so no equivalent exists here.

Four plain lines on a consent screen are more honest than one line that expands to everything.

Scopes cannot be mixed across APIs

MerchantFlow runs two APIs behind one authorization server: this one and the MCP server for AI clients. A single authorization request cannot ask for both mcp:* scopes and Public API scopes - it is rejected with invalid_scope before the merchant sees a consent screen.

If you genuinely need both surfaces, run two authorizations and hold two tokens.

Changing scopes later

Send the merchant through the authorization flow again with the new scope set. Their existing connection is updated rather than duplicated, and they see the consent screen again with the new permissions.

Narrowing takes effect immediately: a token can never grant more than the current authorization allows, even if it was issued with a wider scope list.

Next

• Incremental sync
• Endpoints

Last updated: September 22, 2026