Docs menu

Read-only mode and the mirror lock

Until an organization goes live, nothing leaves Manifold, and records imported from another system stay as that system says.

Why

A business moving to Manifold runs it beside the system it is leaving until it trusts it. If both wrote to the same store, ledger or inbox, they would overwrite each other. So a new organization starts read-only, and an owner or admin decides when Manifold starts acting for the business.

What read-only holds back

While an organization is read-only, Manifold sends nothing outside itself for it:

  • no stock, prices, products or fulfilments sent to its sales channels;
  • no entries posted to its accounting system;
  • no email to its customers or suppliers;
  • no webhooks to apps other than Manifold's own.

Everything coming in carries on: orders from sales channels, imports, and people's own work in Manifold. A refused send is recorded with the reason: an email shows as not sent, a sales channel push is refused.

In the admin, a Read-only badge sits at the top of every page. The decision is in Settings › General, under Read-only mode.

Going live

An owner or admin presses Go live and types "go live" to confirm. Through the API it is POST /api/auth/organizations/{organizationId}/go-live.

  • It is final. Asking for read-only afterwards is refused 409 GoLiveIsFinal.
  • It opens the books. The opening stocktake completes in the same step. A stocked SKU with no cost entered and no cost basis holds it back: 409 OpeningStocktakeIncomplete names the SKUs. If inventory does not answer, it is refused 503 OpeningStocktakeUnavailable. Either way nothing changed; fix it and go live again. See Going live, step by step.
  • Nothing held back is sent late. Each integration catches up from things as they stand: a store at its next stock check, the ledger at its next sync.
  • The app for the system you are leaving is retired for good. It finishes the work it has in hand, then gets no more tokens (AppRetired). Installing it again is refused 409 OrganizationAlreadyLive.
  • A sandbox never goes live. It is refused 409 SandboxNeverLive.

Going live again is answered with the organization as it stands, and records nothing new.

What an app must do

Partner apps are not open yet. Today only Manifold's own apps are issued app tokens and receive webhooks. See App tokens.

An app that writes outside Manifold for an organization, to its store, its ledger or its customers, follows the same rule. Ask where the organization stands at the moment you would send:

curl 
curl -X GET 'https://auth.getmanifold.io/api/auth/mode' \
  -H "Authorization: Bearer $MANIFOLD_TOKEN"

Any token for the organization can ask, a person's included. The answer is that organization's alone.

Response · 200 · read-only 
{
  "organizationId": "org_01a156d2-8680-7738-ab2e-ff985e454887",
  "mode": "read-only",
  "changedAt": "2026-10-20T01:00:02.000Z",
  "changedBy": "usr_01a15709-7582-7646-b491-261a138f0650"
}
Response · 200 · live 
{
  "organizationId": "org_01a156d2-8680-7738-ab2e-ff985e454887",
  "mode": "live",
  "changedAt": "2026-10-22T00:00:00.000Z",
  "changedBy": "usr_01a15709-7582-7646-b491-261a138f0650"
}
  • read-only: do not send. Keep your place, and catch up from the current state once it is live.
  • No answer: do not send either. Try again later. An outage should delay a send, never let one through.
  • Do not read it from the token. A person's token says whether the organization was read-only when it was issued, up to 15 minutes ago.
  • You may remember the answer for a few minutes; Manifold's own services keep it for five. Forget it when the organization.mode-changed webhook arrives, and ask again. Do not act on the webhook's own mode: a late or repeated delivery can be out of date.

While an organization is read-only, an app other than Manifold's own receives no webhooks from it. Its first will be organization.mode-changed, when the organization goes live.

The mirror lock

If you imported from another system and chose to keep following it, Manifold re-reads that system on a schedule and copies across what changed. Until you go live, that system's figures win. An edit made in Manifold would be overwritten, or would drift from them.

So people cannot change those areas. A write is locked when every scope that would allow it is one of these:

products:write, catalogs:write, stock:write, receiving:write, allocations:write, locations:write, orders:write, payments:write, purchasing:write, customers:write, companies:write.

A locked write is refused 409, naming the system:

Response · 409 
{
  "_tag": "MirroredFromSource",
  "source": "cin7-core"
}
  • Who is locked: people. Members, their AI agents, a partner's staff, and a Manifold administrator acting as one of them.
  • Who is not: Manifold's own sync, which is how the other system's data arrives, and apps, which write under their own grant.
  • What stays open: settings, the chart of accounts, your team members and their roles, sales channels, apps and billing.
  • What locks nothing: a one-off import, an import someone stopped following (Stop following in Settings › General), and a sandbox, whose copy is its own.

The badge reads Read-only · following and the system's name. The lock is carried in the person's token, so a change can take up to 15 minutes to reach every call.

Going live lifts the lock. There is no separate switch. Manifold reads the other system one last time: if you brought your order history across, the orders still open there become live orders in Manifold. Then it stops following, and the records are yours to edit.

Reference