Marketplace

The marketplace is where every SalesOS organization finds and installs apps. Your own organization can always install any version of an app it publishes (for testing); every other organization can only install versions a SalesOS reviewer approved. Installing still goes through the normal consent screen, so admins see exactly which scopes and components they grant.

Before you submit

1. Publish the app version (Settings → Apps → Publish, or POST /v1/apps/published/versions). The app's OAuth app must be multi-tenant and allow every scope the manifest requests.

2. Fill in your publisher profile (Settings → Apps → Publish → Marketplace publisher profile): the name customers see, your website and a contact email for review updates.

3. Declare your domains. UI extensions must be served from a declared domain (or a subdomain of one). Verify at least one domain to earn the verified badge:

   • a DNS TXT record at _salesos-publisher.<domain> with the value salesos-publisher-verification=<token>, or
   • a file at https://<domain>/.well-known/salesos-publisher.txt containing the same line.

   SalesOS reads the TXT record first, then the file over https (public addresses only, 4 KB, 5 seconds). The token is shown next to the domain.

4. Write the listing: tagline, description (Markdown — HTML and images are not rendered), up to three categories, up to eight https screenshot URLs, pricing (free, or paid and billed by you outside SalesOS, with a note), and support, privacy policy and terms URLs.

Submitting

Choose the version, explain why the app needs each scope, add notes for the reviewer (a test account, how to try the app) and submit. "Run checks" shows the same automated checks without submitting.

Justifications are shown to customers on the listing, next to the plain-language description of each scope.

Review workflow

DRAFT ──submit──▶ SUBMITTED ──reviewer starts──▶ IN_REVIEW ──▶ APPROVED
                                                         ├──▶ CHANGES_REQUESTED  (fix and resubmit the same version)
                                                         └──▶ REJECTED           (publish a new version to try again)

• One submission per app is open at a time; withdraw it to submit another version.
• Each submission is one specific app version, and its listing text is snapshotted: the marketplace keeps showing the last approved text until a newer submission is approved.
• Reviewer notes are visible to you in the review history, and you can reply there. Reviewers also keep internal notes you never see.
• You get an email on every status change (to the submitter and your publisher contact email). Without email on a deployment, the status is in the publisher console.

Updates and re-review

An approved app can ship new versions. Whether a person reviews them depends on what changed, compared with the approved version:

SalesOS operators set the policy: automatic approval for unchanged permissions always (default), only for patch releases (x.y.Z), or never. Installed organizations see an update only once a version is approved, and upgrading still shows them what the new version adds.

Suspension

SalesOS can suspend a listing that breaks the marketplace policy or puts customers at risk. A suspended listing disappears from the marketplace; the operator chooses whether new installs and upgrades are blocked and whether the app's access is revoked in every installing organization. Revoking also switches off the app's webhooks, custom actions, before-save hooks, functions, workflows and flows there (nothing is deleted) and the installation shows Suspended by SalesOS. You get the reason by email and in the publisher console.

When the listing is reinstated, the operator either switches those components back on in every organization or leaves it to each organization: an org admin turns the app back on from Settings → Apps (POST /v1/apps/installations/{id}/resume), which also reconnects the access it had.

Ratings and reviews

Each organization that has had the app installed can post one review (1–5 stars and text); posting again edits it. You can reply publicly from the publisher console. SalesOS moderators can hide a review.

Public read API

The approved catalog is public — no credentials, rate-limited per IP. Changes appear within about a minute:

The publisher and review APIs (/v1/marketplace/publisher/*, /v1/marketplace/me/*) take a signed-in session only — API keys and OAuth tokens are refused, as for every app management route.

from salesos import SalesOS

for listing in SalesOS().marketplace.iterate_listings(category="data-enrichment"):
    print(listing["name"], listing["rating"]["average"], listing["installCount"])

Checklist

• OAuth app is multi-tenant and allows exactly the scopes you need
• Every WRITE_* and action scope has a justification a customer would accept
• Privacy policy, support and terms URLs are live
• UI extensions are served from a verified domain
• Icon, tagline, description, categories and screenshots are filled in
• Your endpoints verify X-SalesOS-Signature and respond within their timeouts
• Notes for the reviewer explain how to try the app