Go live

Every new app starts in draft: you can build, test and iterate freely against your own org’s sandbox businesses, but the OAuth flow refuses to connect the app to any real business. Review is what removes that restriction — it’s enforced server-side at both the consent step and the authorization-code exchange, not just a console badge.

App review vs. listing review

This page is about app review — the one gate every app needs, whether or not it’s embedded, whether or not it’s ever listed. It controls exactly one thing: can your app complete authorization against a real (non-sandbox) business.

If you also want to appear in the marketplace, that’s a second, separate, additional gate: listing review. A listing can’t even be submitted until the underlying app is APPROVED here (APP_REVIEW_REQUIRED otherwise) — but plenty of approved apps run in production without ever being listed, onboarding businesses through their own OAuth authorization flow.

	App review (this page)	Listing review
Unlocks	Authorizing against real businesses	Marketplace discoverability
Required for	Every app, always	Only apps that want to be listed
Checks	Scopes match your description, security/error handling self-certification	Listing content, assets, mandatory webhooks, design and content guidelines
Prerequisite	None	This app review, already APPROVED

Review states

DRAFT ──submit──▶ SUBMITTED ──▶ IN_REVIEW ──▶ APPROVED
                                    │
                                    ├──▶ CHANGES_REQUESTED ──resubmit──▶ SUBMITTED
                                    └──▶ REJECTED ──────────resubmit──▶ SUBMITTED

State	Meaning
DRAFT	New app; sandbox-only.
SUBMITTED	Waiting for a reviewer to pick it up.
IN_REVIEW	A reviewer is actively working it.
CHANGES_REQUESTED	Sent back with feedback — visible in the console. Fix and resubmit.
REJECTED	Declined, with feedback. You may resubmit.
APPROVED	Live — the app can connect to any OneBooks business.

DRAFT, CHANGES_REQUESTED and REJECTED can be (re)submitted; SUBMITTED, IN_REVIEW and APPROVED cannot.

Submitting

Only org admins can submit. The console’s submission wizard collects:

• Description — what the integration does and who it’s for.
• App URL — your product’s site.
• Privacy policy URL and Terms URL.
• Support email (support phone optional).
• Demo video URL (optional, but a 3-minute walkthrough of the OAuth connect flow plus your core sync speeds reviews up considerably).
• A self-certification checklist:
  • tested end-to-end against a sandbox business,
  • errors are handled (401 refresh, 429/5xx backoff),
  • client secret and tokens are stored securely.

What reviewers look for

Request only the scopes your description justifies. A “read-only reporting dashboard” asking for fiscal-year:write is the fastest way to CHANGES_REQUESTED.

After approval

Approval unlocks the authorization flow for any business — your onboarding flow can now send real merchants through OAuth consent. Sandboxes keep working as before.

Widening scopes re-gates your app

Editing an approved app’s registered scopes to include any scope not in the reviewed set immediately resets it to CHANGES_REQUESTED: new authorizations against real businesses stop working until you’re re-approved. Narrowing or keeping the set unchanged has no effect. Plan scope additions as a release, not a hotfix.

Note that already-issued tokens and consents are not what review gates — the gate applies to completing new authorizations.

Launch checklist

1. All scopes trimmed to what the integration actually uses.
2. Refresh logic single-flighted; family-burn recovery path tested (Authentication).
3. Webhook signature verification live, test delivery verified (Webhooks).
4. Idempotency keys on every write you might retry (Integration patterns).
5. Review submitted with accurate URLs and support contacts.

If OneBooks suspends your app

OneBooks can suspend an app — for a security problem, a breach of the developer agreement or the review guidelines, or a risk to merchants’ data. Suspension takes effect at once, in every business, and is designed to stop your app touching merchant data without destroying anything:

• Tokens are refused immediately. Every API call with your app’s tokens gets 401, every grant on /oauth/token — refresh and token exchange included — answers invalid_client, and /oauth/introspect reports your tokens { "active": false }. No grace period.
• Nobody can authorize it. The consent screen doesn’t open (it reports Invalid client_id), POST /oauth/device/authorize refuses new device codes with invalid_client, and a device code already on a user’s screen reads as invalid or expired on the approval page.
• Your listing is hidden from the marketplace, in the app and on the public site, and nobody can install your app.
• Merchants can’t open it anywhere. There’s no Open app button, it drops out of their sidebar, its extensions stop rendering, its address in OneBooks shows Suspended by OneBooks, and Installed apps and the connected apps on Integrations mark it the same way. Installations aren’t removed and nothing is deleted — a merchant can still manage or uninstall it.
• Hosted function runs are skipped (SKIPPED, This app has been suspended by OneBooks), including runs already queued.
• Webhook deliveries stop: nothing new is sent, queued or retrying deliveries are dropped, and none can be redelivered.

Your organization’s admins get an email, <app> was suspended, with the reason. The developer console stays available to you, and the app stays in your app list, marked Suspended by OneBooks; its Overview tab shows the date it was suspended and the reason. (An app you’ve deleted isn’t listed, suspended or not.) Scripting it, GET /developer/orgs/:orgId/apps and GET /developer/apps/:id return the date and reason as adminSuspendedAt and adminSuspensionReason — both null while the app isn’t suspended.

Fixing the problem doesn’t lift the suspension by itself: fix what the reason describes, then contact OneBooks developer support at developers@getonebooks.com to have it reviewed. When the suspension is lifted, your app works again for the businesses that still have it installed: refresh your stored tokens as usual, and use the Events API to catch up on changes — events recorded while you were suspended were never delivered to your webhooks.

If OneBooks suspends a developer account

OneBooks can also suspend a developer account — yours or a teammate’s. That turns off every app of every organization the account belongs to, and the console marks each of those apps Held: A developer in this organization is suspended, so OneBooks has turned this app off until the suspension ends or they leave the organization. Its Overview tab says the same, under Held while a developer account is suspended. The organization’s other members keep using the console.

While an app is held:

• Businesses can’t install or open it, and its webhooks and hosted functions don’t run. Merchants see it as Suspended by OneBooks.
• Its tokens are gone. Every access and refresh token issued to it was revoked when the account was suspended, and reinstatement doesn’t restore them: once the app is back you need new tokens for each business — a fresh authorization, or a token exchange the next time a merchant opens an embedded app.
• Nobody in the organization can reactivate it — not an org admin, not the developer who created it. Questions go to developers@getonebooks.com.

OneBooks turns the apps back on itself once no member of the organization is suspended any more — when it reinstates the account, or when the suspended member leaves the organization. With two members suspended, reinstating one leaves the organization’s apps held; they come back when the last one is reinstated or leaves the organization. An organization the reinstated developer shares with no suspended member gets its apps back straight away. Scripting it, GET /developer/orgs/:orgId/apps and GET /developer/apps/:id return deactivatedBySuspension: true for a held app — always false for a live one.

When more than one applies

An app is live only while three things hold: you haven’t deleted it, no developer-account suspension in your organization is holding it off, and OneBooks hasn’t suspended the app itself. Lifting one of those suspensions doesn’t override the other, and it never revives an app you deleted. Merchants see Suspended by OneBooks while OneBooks has suspended the app itself or a developer account holds it; No longer available is only for an app you deleted.