# CherrySub from A to Z

CherrySub connects App Store and Google Play purchases to customer access and subscription reporting. A project contains your team and apps. Each app connects store identities, credentials, products, customers, and delivery settings.

This handbook covers the hosted dashboard, the public-client SDKs, the trusted server integration, the CLI, the HTTP APIs, and self-hosted operation. It documents the current staging preview, reviewed against the implementation on September 9, 2026. Read [release status](/docs/limits-and-release-status) before planning a production rollout.

## Choose your starting point

| Your task | Start here | You will finish with |
| --- | --- | --- |
| Integrate a new app | [First verified purchase](/docs/quickstart) | A sandbox transaction and an active access level |
| Connect an existing store | [App Store](/docs/app-store), [Google Play](/docs/google-play), or [CLI](/docs/cli) | An app credential and a notification plan |
| Add purchase handling | [Authentication](/docs/authentication), then your SDK guide | A customer token, safe purchase submission, and completion |
| Investigate a customer | [Customers](/docs/customers) | The relevant identity, transaction, access state, and evidence |
| Understand a chart | [Charts](/docs/analytics), [metric definitions](/docs/metrics), and [cohorts](/docs/cohorts) | The correct filters, denominator, currency, and time window |
| Receive backend updates | [Webhooks](/docs/webhooks) | A signature-verified, idempotent receiver |
| Operate the service | [Self-hosting](/docs/self-hosting) and [security](/docs/security) | A configured origin, recovery procedure, and monitoring plan |

## The product model

| Concept | Meaning | Example |
| --- | --- | --- |
| Project | Membership and app ownership boundary | A company or product team |
| App | One CherrySub app, with an Apple identity, Google identity, or both | Your iOS and Android product |
| Product | A store SKU | `pro.monthly` |
| Access level | A stable capability your application checks | `pro` |
| Product access mapping | A versioned rule connecting a SKU to access | Apple `pro.monthly` grants `pro` |
| Product set | An ordered presentation of packages | `default` |
| Package | A named slot in a product set | `monthly_ios` |
| App User ID | An identity chosen by your authenticated application | An opaque user UUID |
| Customer | CherrySub's app-scoped identity record | The aliases, purchases, and access for that user |
| Event | Immutable evidence of a verified observation or derived change | A receipt observation or `access.changed` |
| Transaction | The current projection of a store purchase | A particular purchase or renewal |

Use these names consistently. A product set controls presentation; an access level controls access. Creating one does not create the other. CherrySub does not create store SKUs when you register products in its dashboard.

## How a purchase becomes access

1. Your app authenticates the user with your backend.
2. Your backend mints a customer token using an app secret key.
3. Your app purchases through StoreKit or Google Play Billing.
4. The SDK submits the signed transaction or purchase token to CherrySub.
5. CherrySub verifies the store evidence, app identity, and customer-token subject before writing an event.
6. In the same transaction, it updates purchase ownership, store projections, mapped access, and any matching outbound delivery work.
7. The SDK completes the storefront purchase after backend acceptance. Your app reads the subscriber's access levels.
8. Store notifications and reconciliation provide later authoritative observations for renewals, refunds, and missed changes.

A cancelled subscription can remain active until its verified expiry. An inactive grant from one product does not remove access supplied by another active grant. Use the subscriber response for the current access decision.

## What the current preview includes

The dashboard provides projects, apps, account and team management, store credentials, API keys, products, access mappings, product sets, customers and notes, transactions, events, charts, saved analyses, exports, and webhook delivery inspection. The CLI automates credential setup and basic project/app administration.

Swift, Kotlin, Dart, TypeScript, Flutter storefront adapters, and a trusted Go package are implemented in the source repository. Their existing AppVisionOS package names are intentional. Public package registry publication is not available in this preview; SDK guides describe source-based integration.

This release is not a hosted paywall editor, experimentation service, tax/proceeds calculator, or store refund-issuance console. Those capabilities must not be inferred from a similarly named RevenueCat feature. See [limits and release status](/docs/limits-and-release-status) for the precise boundaries.

## Read the whole handbook

Use the chapter navigation to read in order, or search by a screen, metric, API field, or error. [Download the complete handbook](/docs/cherrysub-handbook.md) to keep every chapter together. The [OpenAPI contract](/docs/openapi.yaml) is available separately for tooling.