Publishing your app

A listing makes your app discoverable in the OneBooks marketplace — in the app, under Apps → Marketplace, and on the public marketplace at getonebooks.com/apps (opens in a new tab). It’s separate from app review — see App review vs. listing review for how the two relate. You can run an approved app entirely without a listing — businesses then connect through your own OAuth authorization flow. A listing adds the marketplace page, ratings and reviews, and for embedded apps the one-click managed install. What merchants see walks through the listing, install and uninstall screens from their side.

Everything on this page is managed on your app’s Listing tab in the console. Saving, submitting, withdrawing, unpublishing and replying to reviews need org admin rights; any member can view the tab.

Listing fields

Field	Rules
`name`	Required, ≤ 40 characters
`tagline`	Required, ≤ 80 characters
`description`	Required, 80–4,000 characters (the English text needs at least 80). Plain text; separate paragraphs with a blank line.
`features`	A short bullet list: up to 8 items of ≤ 120 characters
`category` + `secondaryCategories`	One primary category, plus up to 2 secondary ones (no repeats)
`pricingModel` + `pricingDetails`	See Pricing below; `pricingDetails` ≤ 300 characters
`websiteUrl`, `privacyPolicyUrl`, `termsUrl`	Required, `https`
`supportEmail`	Required, a valid email address
`supportUrl`, `docsUrl`, `videoUrl`	Optional, `https`
`installUrl`	`https`; required if your app has no App URL (a redirect-install app)
`countries[]`	Two-letter ISO codes (`AE`, `SA`, `IN`, …); empty means every country
`languages[]`	The languages your app itself supports: any of `en`, `ar`, `es`, `fr`, `pt`
`slug`	Optional — the listing’s URL name (`/apps/<slug>`), lowercase letters, numbers and hyphens, ≤ 50 characters. Generated from the name if you leave it out, and fixed once the listing has been published.
Icon, screenshots	See Assets below

name, tagline, description, features and pricingDetails are localized: { en, ar?, es?, fr?, pt? }. English is required; other languages fall back to English automatically, so shipping English-only is valid — you just reach fewer merchants in their own language until you add translations. The limits apply to every language you provide.

countries[] decides where you’re listed: the in-app marketplace only shows a business apps available in its own country. Every optional field accepts null to mean “not set”, exactly like leaving it out, and an optional URL saved blank is stored as null.

A field problem on save fails with LISTING_VALIDATION_FAILED, and the message lists every problem found. A slug another app already uses fails with SLUG_TAKEN — including when another app claims it a moment before your save lands. And if two first saves of the same listing race (two tabs, a double-click), the one that loses gets 409 LISTING_EXISTS: reload the listing and save again.

Assets

Asset	Size	Format	Limit
Icon	Square, 256–2048 px	PNG, JPEG or WebP (no SVG)	≤ 512 KB
Screenshots	800–3840 px wide	PNG, JPEG or WebP (no SVG)	≤ 2 MB each, up to 6

Files are checked by their contents, not just the extension — renaming a .svg to .png won’t pass. You need an icon and at least one screenshot to submit.

An uploaded asset can’t be deleted while any revision that’s live or could still go live uses it — the published one, or a draft, submitted, in-review, changes-requested or rejected one. Deleting it fails with ASSET_IN_USE. Take it out of your draft and save first (withdraw a submission under review before editing it); an asset the published revision shows stays in use until a revision without it has been approved. Only superseded revisions no longer count.

Pricing

pricingModel is one of FREE, FREEMIUM, PAID or FREE_TRIAL — shown to merchants as Free, Freemium, Paid and Free trial, and usable as a marketplace filter.

Submitting

The Listing tab’s Ready to submit? checklist tracks the requirements below.

Your app itself is approved. It must have passed app review — otherwise submission fails with APP_REVIEW_REQUIRED.
Save the listing with every required field. There must be a saved draft to submit (LISTING_DRAFT_REQUIRED otherwise) with changes that aren’t live yet (LISTING_NOTHING_TO_SUBMIT otherwise).
Upload an icon and at least one screenshot — or submission fails with LISTING_ASSETS_REQUIRED.
Configure how merchants install it. An embedded app needs an https App URL (APP_URL_MUST_BE_HTTPS); an app without an App URL installs by redirect and needs an https installUrl (INSTALL_URL_REQUIRED).
Subscribe to the mandatory webhooks: one active webhook subscribed to both app.uninstalled and business.redact — or submission fails with MANDATORY_WEBHOOKS_MISSING.
Select Submit for review. A listing that’s already SUBMITTED or IN_REVIEW can’t be submitted again (LISTING_UNDER_REVIEW).

A reviewer works through the listing & review guidelines checklist and either approves it — it goes live straight away — or sends it back as CHANGES_REQUESTED or REJECTED with a note. Your organization’s admins get an email for every decision, and the note shows on the Listing tab. Both outcomes can be fixed and resubmitted. Approval also re-checks that every icon and screenshot the revision names still exists; if one doesn’t (LISTING_ASSETS_MISSING), the reviewer requests changes so you can upload it again.

While a submission waits for review, the listing is locked: saving fails with LISTING_UNDER_REVIEW. Withdraw it to make changes — the revision goes back to draft (LISTING_NOT_UNDER_REVIEW if there’s nothing to withdraw).

Editing a live listing

Editing a PUBLISHED listing doesn’t change what merchants see immediately — it creates a new draft revision. Merchants keep seeing the last approved revision until your edit is itself reviewed and approved, at which point it becomes the new live revision and the old one is marked SUPERSEDED. This is deliberate: it stops a bait-and-switch where an app’s marketplace copy is changed to something unreviewed after approval.

Some of what merchants see is live rather than reviewed copy: your app’s requested scopes (What this app can access) and your active hosted functions’ egress hosts (Where your data goes). Keep both accurate — widening an approved app’s scopes sends it back through app review (Go live).

Unpublishing and republishing

Unpublish takes a published listing out of the marketplace (it becomes DELISTED) without touching existing installations — businesses that already installed your app keep using it. You can Republish a listing you unpublished yourself at any time. A listing that OneBooks delisted can’t be republished from the console (CANNOT_REPUBLISH) — contact OneBooks developer support at developers@getonebooks.com.

Ratings and reviews

Once a listing is live, merchants whose business has installed your app — even if it has since uninstalled it — can rate it from 1 to 5 stars with an optional title and a short review. The listing shows the average and the count, and so does your app’s Analytics tab.

You can reply publicly to any review from the Reviews panel on the Listing tab — Post reply (or Save reply to change it later), up to 1,000 characters. Your reply appears under the review on the listing, labelled Reply from <your app’s name>. OneBooks may hide a review that breaks its policies; you’ll still see it in the panel, marked Hidden by moderation, but it no longer counts toward your rating.

Statuses

Listing: UNLISTED → PUBLISHED ⇄ DELISTED. Revision: DRAFT → SUBMITTED → IN_REVIEW → APPROVED (or CHANGES_REQUESTED / REJECTED, both resubmittable; an approved revision that’s later replaced becomes SUPERSEDED).

Where next

Listing & review guidelines — the checklist reviewers actually use.
What merchants see — your listing, install flow and app from the merchant’s side.

Privacy Cookies