canonical: https://jentic.com/apis/merchantflow.ai/merchantflow # MerchantFlow Public API The MerchantFlow Public API gives an authorised application read-only access to an e-commerce merchant's headline metrics, order economics, products, and profit and loss. Single-figure endpoints return the Marketing Efficiency Ratio, D2C gross revenue, ad spend, or contribution profit for a date range, while the orders endpoint returns each order's revenue, COGS, fees, and profit with a cogs_coverage_pct and a pseudonymous customer_ref instead of customer PII. Profitability endpoints return an aggregate P&L and a daily series, and every call uses OAuth 2.1 with PKCE and narrow per-figure scopes such as metrics:mer:read. ## For AI agents Read a merchant's MER, revenue, ad spend, and contribution profit for a date range, sync orders with their per-order economics, list products with current costs, and pull aggregate or daily profit and loss, all read-only. ## Scope Does not create or edit orders, products, or ad campaigns, and does not return customer contact details. Use for reading store metrics, order economics, product costs, and profit and loss only. ## Capabilities - Read the Marketing Efficiency Ratio for a from and to date window, computed as D2C gross revenue over deduplicated blended ad spend - Fetch D2C gross revenue, advertising spend, or contribution profit for a window as single figures - Sync orders incrementally with updated_after, including revenue, COGS, fees, profit, and cogs_coverage_pct per order - Filter orders by created_after, created_before, and sales_channel d2c or b2b, paging with limit and cursor - List products with their current costs and fetch one product by id - Pull an aggregate profit and loss summary or a daily P&L series between start_date and end_date ## Use cases ### Agent-run weekly performance brief through Jentic A founder's agent writes a Monday brief on how the store did last week. Through Jentic it reads MER, D2C gross revenue, and ad spend for the window, then contribution profit, and explains what moved. Because each metric has its own narrow scope, the merchant can approve just those figures, and the OAuth token stays in your own Jentic One instance rather than in the agent's context. Example prompt: Call GET `/metrics/mer`, GET `/metrics/revenue`, GET `/metrics/ad-spend`, and GET `/metrics/contribution-profit` each with from '2026-11-02' and to '2026-11-08', and summarise the four figures ### Incremental order economics sync Finance and BI tools need per-order economics kept current. The orders endpoint takes updated_after and returns results oldest-change-first, including orders whose COGS, fulfilment cost, or attribution were corrected later, so the updated_at of the last processed record is a safe resume watermark. Each order carries cogs_coverage_pct, and ad_spend_allocated is a blended daily allocation rather than measured per-order spend. Example prompt: Call GET /orders with updated_after '2026-11-08T00:00:00Z' and limit 250, follow the cursor until no more pages, and return orders whose cogs_coverage_pct is below 80 ### Daily profit and loss monitoring Operators watch daily profit to catch problems early. The daily profitability endpoint returns a P&L series between start_date and end_date, and the summary endpoint returns the aggregate for a period, including COGS, expenses, and net profit. These need the broader profitability:read scope, so integrations that only need one figure should use the metrics endpoints instead. Example prompt: Call GET `/profitability/daily` with start_date '2026-10-10' and end_date '2026-11-08', then flag any day where net profit was negative ### Product cost review Margin depends on accurate product costs. The products endpoint lists products with their current costs, filterable by status and pageable with limit and cursor, so an agent can spot products with missing or stale costs that would inflate order margins. Example prompt: Call GET /products with limit 250, page through all results, and list products whose current cost is missing ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/metrics/mer` | Marketing Efficiency Ratio for a window | | GET | `/metrics/contribution-profit` | Contribution profit for a window | | GET | `/orders` | List orders with their economics | | GET | `/orders/{id}` | Fetch one order | | GET | `/products` | List products with current costs | | GET | `/profitability/summary` | Aggregate profit and loss | | GET | `/profitability/daily` | Daily profit and loss series | ## Key resources - **Stores** — The connected store with name, currency, timezone, and data freshness - **Metrics** — Single figures for MER, D2C gross revenue, ad spend, and contribution profit - **Orders** — Orders with revenue, COGS, fees, profit, cogs_coverage_pct, and a pseudonymous customer_ref - **Products** — Products with their current costs - **Profitability** — Aggregate and daily profit and loss ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 72 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 99 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 50 / 100 - Agent Usability: 94 / 100 - Security: 90 / 100 - AI Discoverability: 82 / 100 - **View full report:** https://jentic.com/apis/merchantflow.ai/merchantflow/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring MerchantFlow by hand means running OAuth 2.1 with PKCE S256, sending the RFC 8707 resource indicator at authorize and token time, requesting offline_access for a refresh token, and asking for the right per-figure scope on each call. Through Jentic you install once, import MerchantFlow from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** Every MerchantFlow endpoint is a GET, so a Jentic rule bounds which reads your agent may call: the single-figure metrics, orders, products, or the full P&L. You choose the operations it may call, so order economics and the profitability waterfall are not included unless you add them. - **Credential handling:** Your MerchantFlow OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'get marketing efficiency ratio' or 'sync changed orders', and Jentic returns the matching MerchantFlow operation with its input schema, including from, to, and updated_after, so the agent calls the right endpoint directly. ## Related APIs - **Northbeam API** — Marketing attribution that blends ad-spend records across channels - **Shopify API** — Commerce platform holding the store's orders, products, and customers - **Xero Accounting API** — Accounting ledger with invoices, bills, and financial reports ## FAQ ### What authentication does the MerchantFlow Public API use? Per its OpenAPI spec, MerchantFlow uses OAuth 2.1 authorization code with PKCE (S256 required), with the RFC 8707 resource indicator sent at both the authorize and token endpoints. Each endpoint needs a specific scope, such as metrics:mer:read, orders:read, or profitability:read, and requesting offline_access returns a refresh token; without it the access token expires after one hour. Through Jentic the token is stored encrypted by your own Jentic One instance and injected at call time. ### Can I sync only the orders that changed with the MerchantFlow API? Yes. Pass updated_after to GET /orders and you receive only orders changed since then, including ones whose COGS, fulfilment cost, or attribution were corrected later. Results come oldest-change-first, so the updated_at of the last record you processed is a safe watermark, and limit (up to 250) with cursor pages through the rest. ### What are the rate limits for the MerchantFlow Public API? The OpenAPI spec does not specify rate limits. List endpoints accept a limit of up to 250 records per page. Check the MerchantFlow documentation at https://docs.merchantflow.ai/docs/integrations/api for current limits. ### Is there a MerchantFlow MCP server? You don't need an MCP server to give your agent MerchantFlow. Jentic connects it directly from the API Directory: import it, store your OAuth credential once, and your agent calls the metrics, orders, and profitability reads it needs on demand without loading another server's tool definitions into its context. ### How do I read a store's MER through Jentic? Search Jentic for 'get marketing efficiency ratio', load the GET `/metrics/mer` operation, and execute it with from and to dates. The mer value is D2C gross revenue divided by deduplicated blended ad spend, excludes wholesale revenue, and is null when no ad spend was recorded. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the MerchantFlow API? Yes. The API is already read-only, and you can go further: write a rule that allows only GET `/metrics/mer` and GET `/metrics/revenue`, so the agent can report the ratio and revenue but cannot read order economics or the full P&L. Every call it makes is logged. ### Does the MerchantFlow API return customer personal data? No. Customer names, email addresses, phone numbers, and shipping addresses are never returned. Orders carry customer_ref, a pseudonymous identifier that is stable for your application and one merchant and cannot be correlated with other applications' identifiers.