The Commerce order-management API still exists — but the product underneath it moved, and Meta’s own docs no longer agree
Ecommerce platforms and retailers keep starting Commerce Platform integrations from documentation pages that were last updated in 2020, while other pages on the same site were updated last month and describe a different model entirely. Here is what is actually verifiable, and what App Review really gates.
The permissions that actually exist
The Commerce permission family is small, and the names matter — a request built around a permission Meta does not publish will not survive contact with the App Review form.
commerce_account_read_orders
Read commerce account orders. Meta’s published Allowed Usage adds a hard restriction: the buyer’s email address may be used for marketing purposes only if the buyer opted in at checkout.
commerce_account_manage_orders
Read and update commerce account orders. This is also the permission that Meta says grants access to webhook notifications, and the one written for tech providers managing orders on behalf of their customers.
commerce_account_read_settings
Read basic commerce account information — connected channels, shipping options, fulfillment locations, connected business.
commerce_account_read_reports
Read finance reporting data to build custom tax, cash reconciliation and reimbursement reports for a commerce account.
catalog_management
Create, read, update and delete business-owned product catalogs the user administers. Meta publishes a dependency: it requires business_management.
business_management
Read and write with the Business Manager API. It carries its own dependencies on pages_read_engagement and pages_show_list — so one apparent feature becomes four permissions to justify.
What App Review actually gates here
Meta is unusually explicit on this one point, and it reframes the whole project plan: before you complete App Review, your app can only access test commerce accounts. You demonstrate the integration on a Test Commerce Account, then submit for App Review to manage a real commerce account.
That single sentence has three consequences most plans miss. Your demo recording must be produced against test data, not a real merchant. Your onboarding flow has to exist before review, not after it. And a pilot with a friendly live seller is not available to you as a shortcut.
The prerequisite chain, in the order Meta requires it
- Settle the asset ownership firstMeta documents that your business must own the Facebook Page, the Catalog, and any Instagram accounts before the Commerce Account is created in Commerce Manager. This ordering is not cosmetic. Meta also states plainly that removing the catalog from your business will delete your commerce account.
- Create a system user and assign assetsMeta recommends system-user-backed tokens because an ordinary user token can be invalidated over time or when that user changes their password. The system user needs admin access to the app, the test commerce account, the backing Page, and the connected catalog.
- Use the right token, with the right roleThe Order Management API acts as the Facebook Page and relies on a Page Access Token. Meta specifies the Page role behind that token must be EDITOR or above.
- Associate the app with the shop — onceBy default a shop is configured to move new orders straight to IN_PROGRESS. Order acknowledgement only becomes possible after a one-time association between your app and the commerce seller settings representing the shop. Skip it and orders never wait in CREATED for you to acknowledge, which reads as a broken integration rather than a missing setup step.
- Only then request permissions and prepare the submissionMeta names over-requesting directly: selecting unneeded permissions is a common reason for rejection. Every permission needs its own justification and its own demonstration.
Request-stage problems vs approval-stage problems
Conflating these is the expensive mistake. A fix aimed at the wrong stage costs weeks and changes nothing.
| Requirement | What it actually stops |
|---|---|
| Asset ownership order (Page, Catalog, then Commerce Account) | Blocks the build — wrong order means rebuilding the account, not resubmitting |
| App not associated with commerce seller settings | Blocks functionality — acknowledgement is unavailable, orders auto-advance |
| Page token below EDITOR role | Blocks the API call itself |
| App Review not complete | Blocks real accounts — test commerce accounts only until approval |
| Business Verification | Meta states it is required for all apps making requests for Advanced Access. No Commerce-specific page restates it. |
| Unneeded permissions in the request | Blocks approval — Meta names this as a common rejection reason |
| Region ineligibility | Blocks eligibility silently until you query it — Meta publishes reason codes for shops and for on-Meta checkout not being available in a region |
Mechanics that quietly break integrations
- Every POST request must include an idempotency_key — an alphanumeric string up to 100 characters. Multiple different requests reusing the same key throw an error.
- Meta’s guidance after a coded exception is to retry with a new idempotency key, not the same one — the opposite of the usual retry instinct.
- Order listing is cursor-paginated with a default maximum of 25 orders per page; acknowledgement batches cap at 100 orders.
- The default returned fields are minimal — id, order_status, created and last_updated. Everything else must be requested.
- Buyer email is fulfillment-only unless the opt-in flag is set. Building marketing on that field without checking the flag is a policy problem, not a bug.
- Orders can be cancelled after leaving FB_PROCESSING, with an exception for orders that have sat in FB_PROCESSING for more than 24 hours.
- Meta states that manual onboarding is acceptable for testing or as a temporary measure but not as a scaled solution — platforms are expected to build the Commerce Manager redirect and on-behalf-of flow.
- A promotions field was deprecated and replaced by promotion_details from v22.0 onward; integrations built on older samples silently read the wrong field.
Four places Meta’s own pages disagree — state them, do not resolve them
- Is the Order Management API invite-only? The "Using the API" page, last updated December 2020, says it is a closed invite-only Beta and to work with your Facebook representative. The API setup page, updated June 2026, describes a self-serve path ending in App Review, with no invite language at all. Both are live.
- Does on-Meta checkout still exist? The architecture page carries a September 2025 end-of-checkout note; the setup, integration and Order API pages updated in 2026 still document the on-Meta flow, including Meta-collected tax.
- Onsite or offsite? Earlier partner guidance told platforms to migrate away from offsite shops and adopt checkout on Facebook and Instagram. The current checkout-URL page says checkout takes place on your own website. Meta reversed direction and left both pages standing.
- Which permission the Order API needs. The setup page names the commerce_account order permissions. An integration best-practices page updated in June 2026 instead names manage_pages — a long-deprecated permission name.
What Meta does not publish — treat any such figure as invented
- No App Review turnaround time for commerce permissions.
- No approval rate, no published pass ratio, and no "most apps get approved" figure.
- No revenue share, selling fee or payout percentage, and no payout timing in days.
- No list of eligible countries or currencies — only ineligibility reason codes.
- No per-permission Standard vs Advanced Access classification on the permissions reference.
- No retrievable webhook reference — webhooks are named as a grant of commerce_account_manage_orders and as an App Dashboard feature, but no topic list, payload schema or retry behaviour is published in the pages available.
- No statement that approvals do or do not survive app changes or ownership transfers.
The part that is genuinely hard
Reading a permission list is not the work. The work is deciding whether an on-Meta order-management integration is still the right architecture given the direction change, choosing the minimum permission set that survives the over-requesting rejection, sequencing the asset creation so the commerce account is not built on a foundation that has to be torn down, and producing a submission where each permission has its own demonstration against a test commerce account and its own written justification matching the Allowed Usage Meta publishes for it. That reconciliation across architecture, recording and text is the part we prepare for clients, and it is why two teams with identical code get different review outcomes.
Related reading: how system user access tokens give SaaS platforms long-lived API access, what Meta Advanced Access actually is, and every way a Meta App Review submission can fail.