# SubKit

> SubKit is the source of truth for product catalog, commerce, and access across mobile and web products. Apps name an entitlement and read SubKit's Effective Access decision; Apple, Google, and payment providers are verified inputs, never competing sources of truth.

## Invariants an integration must never break

- SubKit is the source of truth for Catalog, Commerce, and Access.
- Access always follows: Access Source -> Access Pool -> Reservation/Allocation -> Entitlement Grant.
- Apps name entitlements, never subscription, plan, package, or store-product IDs.
- Mobile apps use only public app-bound SDK keys. Server keys belong only in trusted backends.
- A mobile installation ID is generated once, persisted locally, and reused on every launch.
- Only the Effective Access decision (`access.state === granted`) unlocks access; apps never combine raw entitlement and device fields.
- Store purchases unlock access only after provider verification and a granted Effective Access decision.
- Mutations require the documented capability, an idempotency key, and an audit reason.
- Store reads may run automatically; store writes require preview, explicit confirmation, apply, then verify.

## Documentation sets

- [Abridged documentation](/docs/llms-small.txt)
- [Complete documentation](/docs/llms-full.txt)
- [SubKit mobile documentation](/docs/llms-mobile.txt): Expo SDK setup, offerings, purchases, restore, and offline access.
- [SubKit backend documentation](/docs/llms-backend.txt): Node SDK, server auth, customers, contracts, payments, and access capacity.
- [SubKit concepts](/docs/llms-concepts.txt): Source of truth, catalog, commerce, and the access model.
- [SubKit API reference](/docs/llms-api.txt): Runtime and server APIs, capabilities, contracts, and errors.
- [SubKit operations](/docs/llms-operations.txt): Store setup, security, go-live, and troubleshooting.

## Pages

- [Access model](https://subkit.piparo.tech/concepts/access-model/index.md) — Source → Pool → Reservation/Allocation → Grant. Why every commerce cause resolves to the same access path.
- [Catalog](https://subkit.piparo.tech/concepts/catalog/index.md) — How SubKit models products, plans, immutable plan versions, prices, offers, offerings, and store bindings.
- [Commerce](https://subkit.piparo.tech/concepts/commerce/index.md) — The normalized commerce causes SubKit recognizes, and how payment evidence stays separate from access.
- [Glossary](https://subkit.piparo.tech/concepts/glossary/index.md) — SubKit terminology — public product terms, technical objects, and deliberately avoided legacy terms.
- [Identity and tenancy](https://subkit.piparo.tech/concepts/identity-and-tenancy/index.md) — Tenants, apps, app users, organizations, access subjects, billing accounts, and store environments — and how they relate.
- [Source of truth](https://subkit.piparo.tech/concepts/source-of-truth/index.md) — SubKit owns catalog, normalized commerce events, and derived access. Store and payment providers are verified inputs, never competing truth.
- [Advanced configuration](https://subkit.piparo.tech/expo/advanced/index.md) — Override the purchase queue, CustomerInfo cache, app-state source, adapter bundle, and platform detection.
- [Configuration](https://subkit.piparo.tech/expo/configuration/index.md) — Configure the SubKit Expo SDK — required fields, installation ID, API base URL rules, iap options, and lifecycle.
- [Ownership & unclaimed purchases](https://subkit.piparo.tech/expo/conflicts/index.md) — Ownership states, unclaimed purchases with claim hints, conflict resolution, and family sharing.
- [Checking effective access](https://subkit.piparo.tech/expo/entitlements/index.md) — Gate features with one impossible-state-safe SubKit access decision instead of combining entitlement and device fields in app code.
- [Error handling](https://subkit.piparo.tech/expo/error-handling/index.md) — Domain results vs. thrown errors, retryable flags, normalized IAP errors, and redaction guarantees.
- [React hooks](https://subkit.piparo.tech/expo/hooks/index.md) — The complete React hook surface — effective access, Boolean gates, offerings, and automatic IAP sync.
- [Identifying users](https://subkit.piparo.tech/expo/identity/index.md) — Anonymous start, identify() after login, identity switches, and automatic store identity hints.
- [Installation](https://subkit.piparo.tech/expo/installation/index.md) — Install the SubKit Expo SDK, its core contract, and the expo-iap native adapter.
- [Migrate to effective access](https://subkit.piparo.tech/expo/migrating-effective-access/index.md) — Replace manual CustomerInfo entitlement and device checks with the canonical SubKit access decision.
- [Offerings & paywalls](https://subkit.piparo.tech/expo/offerings/index.md) — Load offerings, render packages with live store prices, and never fall back to static catalog values.
- [Offline access](https://subkit.piparo.tech/expo/offline/index.md) — How cached CustomerInfo behaves offline — freshness states, expiry rules, and the accessContext lifecycle.
- [Expo / React Native](https://subkit.piparo.tech/expo/overview/index.md) — How the SubKit Expo SDK is structured and where to find each integration task.
- [Making purchases](https://subkit.piparo.tech/expo/purchases/index.md) — Run purchases and handle every outcome — verified, pending, cancelled, failed — plus thrown errors.
- [Recipes](https://subkit.piparo.tech/expo/recipes/index.md) — Complete Effective Access patterns — gated screens, paywall preflight, commercial-status UI, restore, and platform facades.
- [Restore & sync](https://subkit.piparo.tech/expo/restore-and-sync/index.md) — Manual restore, automatic sync triggers, sync reasons, and the useSubKitIapAutoSync hook.
- [Testing](https://subkit.piparo.tech/expo/testing/index.md) — Test SubKit integrations deterministically with memory stores, injected adapters, and sandbox purchases.
- [Troubleshooting](https://subkit.piparo.tech/expo/troubleshooting/index.md) — Expo SDK symptoms and their causes — configuration throws, missing store products, stuck pending, missing entitlements.
- [SubKit](https://subkit.piparo.tech/index.md) — SubKit is the source of truth for product catalog, commerce, and access. Apps and backends read entitlements; store and payment providers are verified inputs.
- [Bind checkout to the reviewed selection](https://subkit.piparo.tech/node/checkout-selection/index.md) — Preserve an offering revision from review through guest checkout and retries.
- [License ordering and cursors](https://subkit.piparo.tech/node/license-ordering/index.md) — Read license pages in server order without reusing cursors across selections.
- [Node.js backend](https://subkit.piparo.tech/node/overview/index.md) — Drive SubKit commerce and access from trusted server code — customers, contracts, payments, seats, entitlement checks, idempotency, and errors.
- [Go-live checklist](https://subkit.piparo.tech/operations/go-live/index.md) — What to verify before taking a SubKit-backed product to production.
- [Security model](https://subkit.piparo.tech/operations/security/index.md) — How SubKit handles keys, secrets, verification, and least privilege.
- [Troubleshooting](https://subkit.piparo.tech/operations/troubleshooting/index.md) — Common SubKit integration symptoms and what to check first.
- [HTTP API](https://subkit.piparo.tech/reference/api/index.md) — Runtime and Server endpoint inventory, authentication boundaries, capabilities, and mutation headers.
- [Error model](https://subkit.piparo.tech/reference/errors/index.md) — SubKit error codes, HTTP behavior, retry guidance, and safe user reactions.
- [Reference](https://subkit.piparo.tech/reference/overview/index.md) — SubKit's public surfaces — SDK keys and capabilities, Runtime API, Server API, and the error model.
- [Choose an integration](https://subkit.piparo.tech/start/choose-an-integration/index.md) — Which SubKit surface you use — Expo SDK, Node SDK, Runtime API, or Server API — and the security boundary between them.
- [Quickstart](https://subkit.piparo.tech/start/quickstart/index.md) — The smallest complete SubKit path — configure an app, identify a user, load an offering, run a purchase, and check an entitlement.
- [Apple App Store setup](https://subkit.piparo.tech/stores/apple/index.md) — Connect App Store Connect, configure StoreKit products and Server Notifications V2, and verify an Apple Sandbox purchase through SubKit.
- [Google Play setup](https://subkit.piparo.tech/stores/google-play/index.md) — Connect the Play Developer API, configure authenticated RTDN, bind subscriptions and base plans, and verify a License Tester purchase through SubKit.
- [Stores](https://subkit.piparo.tech/stores/overview/index.md) — How SubKit connects to Apple and Google — verified reads, confirmed writes, and the shared store boundary.