What merchants see
Everything you configure in the console surfaces somewhere in a merchant’s OneBooks. This page follows a merchant’s journey in the order they meet your app and maps each screen to the setting or API behaviour behind it, so you can predict — and design for — what they’ll see. (Quoted labels are the English UI; merchants use OneBooks in English, Arabic, Spanish, French or Portuguese.)
To see it for yourself, browse the live marketplace at getonebooks.com/apps (opens in a new tab), read the merchant help at docs.getonebooks.com (opens in a new tab), or install your app into a sandbox and sign in as its owner.
1. Finding your app
Section titled “1. Finding your app”Merchants browse the App Marketplace under Apps → Marketplace in
OneBooks, or the public marketplace on getonebooks.com, which sends them into
OneBooks to install. They can search by name, filter by category (your
category and secondaryCategories) and by Pricing (your
pricingModel), sort by Most popular, Highest rated, Newest or
Name (A to Z), and see a Featured row that OneBooks curates.
Only published listings of approved, active apps appear, and the
in-app marketplace shows a business only the apps available in its country
(your countries[] — empty means everywhere). Your text appears in the
merchant’s language when you’ve provided it, and in English otherwise.
2. Your listing page
Section titled “2. Your listing page”| What the merchant sees | Where it comes from |
|---|---|
| Name, tagline, icon, By <developer> | Your listing fields and icon; your organization’s name |
| About this app, Features, Screenshots | description, features, your screenshots |
| What this app can access — split into Can view and Can create and modify | Your app’s requested scopes, in the registry’s merchant-facing wording |
| Where your data goes | The declared egress hosts of your active hosted functions — hidden if you have none |
| Pricing, Availability (countries and languages), Links | pricingModel + pricingDetails, countries[] + languages[], your website, support, privacy, terms, docs and demo-video URLs |
| Ratings & reviews | Merchant reviews and your replies |
The access list and the egress hosts are live — they always reflect your app’s current scopes and functions, not a reviewed snapshot. See Publishing your app for every field’s rules.
3. Installing
Section titled “3. Installing”Installing takes the business’s integrations.manage permission — by default
its owner and admins; everyone else sees Ask an admin to install this
app. What happens next depends on how your app installs:
- Managed install (your app has an App URL). A dialog, Install
<your app>?, lists everything your app can do under This app can:,
with the note The app can act on your books through these permissions. You
can uninstall it at any time. Selecting Install app creates the
installation at once with your app’s full set of requested scopes, sends you
app.installed(source: "MARKETPLACE"), and takes the merchant straight to your app’s home page — where your backend gets its first tokens by token exchange. - Redirect install (no App URL). OneBooks asks Continue to <your
app>? and sends the browser to your
installUrl. From there your site runs the standard authorization-code flow: the merchant approves the OneBooks consent screen, you exchange the code, andapp.installedarrives withsource: "OAUTH".
Either way, the result is an ACTIVE
installation for that business.
4. Your app inside OneBooks
Section titled “4. Your app inside OneBooks”- Its own page. An embedded app gets a row under Apps in the sidebar, and an Open app button on its listing and in Installed apps. Your home page opens inside a frame that OneBooks labels: your icon and name, by <your organization>, a menu with Manage app, and the note This content is provided by <your app>, not OneBooks.
- Actions. On an invoice, quote, customer, supplier, purchase, sales return or purchase return, an Apps button appears in the page’s actions once some installed app has an action for it. Your label opens your page in a dialog with the same labelled frame, plus a close (×) button; Escape or a click outside closes it too.
- Blocks. Your cards appear on the record page — and dashboard blocks in a From your apps section on the dashboard. Each card is headed by your label, with a light line under it: Provided by <your app> (<your organization>), not OneBooks.
- App data. Fields you declared as visible appear in an App data card
on the record, grouped under your app’s name. Fields you made editable show a
pencil to merchants who can edit the record itself; their edits reach you as
app_data.updated. - Your requests to the host — confirmations, pickers, toasts, a progress bar while you work — are drawn by OneBooks; a confirmation names your app as the one asking. If you set a title, it appears as a secondary heading beside your app’s name; it never replaces it.
If your page doesn’t call ready within 15 seconds, the frame shows This app
did not load in time with a Retry button; if your URL isn’t https, it
shows This app can’t be shown. Everything your app does is bounded by the
installation’s scopes and the merchant’s own role — a viewer opening your
app gets read-only results.
5. Installed apps and the manage drawer
Section titled “5. Installed apps and the manage drawer”Apps → Installed apps lists every app installed in the business, each card showing Installed by whom, when, and when it was Last active. Selecting Manage (or Manage app in your frame’s menu) opens a drawer with five tabs:
| Tab | What it shows | Behind it |
|---|---|---|
| Permissions | What your app can view and create or modify | The installation’s granted scopes |
| Data | The outside destinations your automations can reach | Your active functions’ egress hosts |
| Activity | Your app’s recent actions in the books, newest first | Every change made with your app’s tokens is recorded against your app |
| Usage | Reads, writes and errors over the last 30 days | Your API traffic in that business |
| Automations | Recent hosted-function runs — Queued, Running, Succeeded, Failed or Skipped | Run statuses (merchants see the status, not your logs) |
Merchants can judge your app by what these tabs show: a steady stream of errors or failed automations is visible to them.
6. Uninstalling — and the 48-hour deletion
Section titled “6. Uninstalling — and the 48-hour deletion”From the drawer, Uninstall asks Uninstall <your app>? — This immediately revokes the app’s access to your books. Any data it stored in OneBooks is deleted after 48 hours unless you reinstall. Here’s what that means on your side:
- Immediately: every token your app holds for that business is revoked
(your next call gets
401), codes and device approvals you haven’t redeemed yet are cancelled, queued webhook deliveries of its events are dropped, and you receiveapp.uninstalled. - 48 hours later, unless the business reinstalls first: OneBooks deletes
your app data in that business and sends
business.redact. You must then delete everything you hold for that business yourself — see Privacy & data handling. - Documents your app created (invoices, payments, …) stay in the books — they’re the business’s records now.
A reinstall within the 48 hours restores the installation with nothing lost.
7. Reviews
Section titled “7. Reviews”A business that has installed your app — even if it has since uninstalled it
— can leave one 1–5 star rating with an optional title and a review of 10 to
2,000 characters; posting, editing and deleting it takes the same
integrations.manage permission as installing. Your
public reply appears under
it.