# Concepts

> Organizations, projects, apps, products, entitlements, offerings, customers and events.

| Concept | Meaning |
| --- | --- |
| Organization / project | Tenancy. People belong to organizations; a project holds all data for one product. API keys are bound to one project. |
| App | A connection to one provider account or store listing. Carries the webhook URL you give the provider. |
| Product | Something sold in a store: a Stripe price, a Braintree plan, an App Store or Play product. |
| Entitlement | A level of access, such as `pro`. Unlocked by any attached product, or granted manually. |
| Offering / package | The products you present to customers, fetched by client apps to build a paywall. |
| Customer | A user, identified by your own `app_user_id`. Earlier ids (an anonymous id merged on sign-in, ids imported from RevenueCat) stay attached as aliases and find the same customer. |
| Subscription / purchase | Normalized state of what a customer bought, whichever provider sold it. |
| Event | `initial_purchase`, `renewal`, `cancellation`, `billing_issue`, `expiration`, `refund` and more. Sent to your webhook endpoints. |

## The access rule

A subscription grants its entitlements while its status is `trialing`, `active` or `in_grace_period`. A cancelled subscription keeps access until the paid period ends. Manual grants add access with an optional expiry.

A period only counts once it is paid. Stripe, for example, rolls a subscription into its next period about an hour before charging; SalesDogg keeps the last paid period (and keeps a trial a trial) until the invoice is paid.

## Environments

Every subscription and purchase is either `production` or `sandbox`. Simulator purchases, Stripe test mode and store sandboxes are `sandbox`. Metrics and lists take an `environment` filter.

## Conventions

- Errors are always `{ "error": { type, code, message, param?, hint? } }`. `hint` says what to do next.
- Creates keyed by `lookup_key`, `app_user_id` or `store_identifier` are idempotent upserts, so retries are safe.
- Lists take `limit` and `starting_after`; responses carry `has_more` and `next_cursor`.
- Money is in minor units (cents). Timestamps are ISO 8601 in UTC.
- Ids are prefixed and time-sortable: `cus_…`, `sub_…`, `evt_…`.