Experience
Keep your paywall, targeting, and experiments. Connect product selection to the app’s existing purchase flow.
Explore this role →Build your part
Build the part your business does well, and connect it to compatible services. The shared contract covers purchase verification, ownership, access, and events. Your product, infrastructure, and customer relationship remain yours.
See two backends use the same clientBuild your connection with AI
Commerce services
Choose your store adapters, database, and service model. Give app backends a defined contract they can test and reuse.
Explore this role →Data & automation
Build a receiver for normalized events, then reuse it across compatible emitters. Own your reports, audiences, and workflows.
Explore this role →The example repository gives AI working code and checks for each connection. Choose the role your business owns, describe the behavior you want, and review the running result.
Two backends, the same user experience#
One app backend. One event receiver. Two commerce providers. The same app backend and receiver ran against the example, then IAPKit, then the example again. The consumer code changed in 0 files.
Follow Alice’s subscription below. These are recorded results from IAPKit’s real server and Convex storage alongside the original SQLite example. Google responses and app sessions are local fixtures; no real payment was made.
The same app verifies the same fixture evidence, connects it to Alice’s session, and reads Premium access.
openiap-commerce-protocol-example
Premium available
Inspect the recorded response
json
{
"userId": "interop_alice",
"productIds": [
"premium.monthly"
],
"subscriptions": [
{
"productId": "premium.monthly",
"state": "Active",
"active": true,
"store": "google",
"expiresAt": 1788979811375,
"willRenew": true
}
]
}IAPKit
Premium available
Inspect the recorded response
json
{
"userId": "interop_alice",
"productIds": [
"premium.monthly"
],
"subscriptions": [
{
"productId": "premium.monthly",
"state": "Active",
"active": true,
"store": "google",
"expiresAt": 1788979811375,
"renewsAt": 1788979811375,
"willRenew": true,
"startedAt": 1788979766600,
"updatedAt": 1788979766630
}
]
}Choose the store your app will use
The same verification, ownership, access, and erasure path also runs for Apple, Amazon, and Meta Horizon. Amazon and Horizon are checked again on access reads, including rejection and upstream failure; their results contain no invented subscription lifecycle records.
Store responses, Apple signature verification, and account sessions are fixtures in this run. It does not establish device checkout. Read the store comparison code.
What your team changes
Choose the provider URL and server credential, register the event receiver, and agree on product IDs and account ownership. Your purchase-to-access code and receiver keep the same contract. A provider switch also needs a plan for existing purchase records: this test sets up the same fixture purchase in each provider; it does not migrate a customer database.
AI can wire those settings and run this check. Your team reviews whether the access, cancellation, and deletion results match your product’s policy.
Read the app, provider, and receiver code
App backend authenticates the session, calls the selected provider, and keeps deletion requests until every provider completes them. Commerce client gets its routes and validators from the installed contract.
Example provider runs the flow in SQLite. IAPKit handlers connect the same operations to store verification and Convex. The shared receiver checks signatures, deduplicates events, and discards erased identities.
The event timing differs: the example emits a grant when Alice is bound. IAPKit combines binding with a store notification. Both produce the same access decision and a correlated grant in this run.
Run the same replacement check
Install dependencies in both checkouts with Bun 1.3.13 and Node.js 24 available. From the OpenIAP repository:
sh
bun install --frozen-lockfile
(cd ../openiap-commerce-protocol-example && npm ci --ignore-scripts)
bun --conditions=openiap-source packages/kit/scripts/docs/run-commerce-interop.mjs \
../openiap-commerce-protocol-exampleThe command creates an isolated local Convex deployment, seeds fictional data, and exits nonzero on a failed assertion. It needs an initial download of the pinned Convex backend. No store credentials, IAPKit account, or cloud deployment variables are needed.
What the evidence covers
170 checks passed on 2026-09-09. The run restarted the actual local Convex process with an event retry pending, reopened SQLite, replayed acknowledged events, and checked provider and recipient erasure.
IAPKit’s route handlers, all four store verification action bodies, Google notification handling, database functions, deletion scheduler, and signing worker execute. External store responses and Apple signature verification are fixtures; the worker’s existing transport hook sends to localhost. Real store purchases and public HTTPS DNS/TLS are separate deployment checks.
The earlier SQLite and memory comparison remains a separate storage-adapter experiment.
Product roles and connection contracts#
| Role | Owns | Connects through |
|---|---|---|
| Experience | Presentation, targeting, and product selection | Client purchase API; provider-specific presentation API |
| Commerce services | Store evidence validation, purchase ownership, and current entitlement state | Core + complete declared profiles and bindings |
| Data & automation | Event ingestion and its own business models and workflows | Webhook receiver rules; no emitter-profile claim merely for receiving |
These are business roles, not new protocol profiles. Paywall layouts, targeting, product catalogs, attribution, and financial reporting remain product-specific APIs. The commerce data contract standardizes verification, ownership, access, and lifecycle delivery.
Paywall specialist: keep the existing purchase runtime#
Return a product selection to the host app’s purchase callback. The app fetches current store products and calls OpenIAP’s purchase API. Your service does not need to become the purchase verifier or account authority.
The composition example includes a host callback adapter you can read and run. It shows pending, canceled, failed, and fulfilled results, and finishes a purchase only after the backend confirms fulfillment. Its purchase callback is a fixture; connect your SDK’s purchase and update listeners in a real app.
Follow a purchase, one step at a time →
Define the product IDs and purchase/result callbacks with the app. That small host adapter belongs to the paywall integration; Commerce Protocol 1.0 does not define a universal paywall UI API. If your product uses lifecycle data, connect its backend with the ready receiver.
The client-to-provider connection#
The current client helper verifyPurchaseWithProvider supports IAPKit’s own API. Changing its provider name or base URL is not a generic Commerce Protocol integration. For another provider, the app’s authenticated backend calls the protocol’s REST or GraphQL operations.
The example’s client-bridge.mjs runs on the app backend, maps Apple, Google, Amazon, and Horizon purchase fields into the installed protocol’s verification inputs and validates them. It also rejects missing evidence and unsupported stores. Run npm run demo:bridge in the example repository; it checks the request boundary, not a live store purchase.
Apple sends its JWS; Google sends its purchase token. Amazon and Horizon require additional store user identifiers and need an explicit store adapter. Keep the application’s authenticated user identity separate from those store identities.
Only the app backend selects userId and holds server-role credentials. Verification is not an access grant: bind under the ownership policy, read current entitlements, and fulfill durably before finishing the store transaction.
Compose services without splitting authority#
Choose one authoritative ownership and entitlement service for an app/project. A commerce service can delegate store verification internally while serving the complete profiles it declares. Separate businesses must agree on opaque user IDs, issuer/project scope, credentials, supported stores, and the selected protocol/profile versions.
An event-only consumer implements receiver rules, not the events emitter profile. A provider implements core discovery and each advertised profile completely; account lifecycle includes erasure. Moving from a specialist to an integrated platform changes service ownership and configuration, while the store purchase flow and commerce payload meanings stay the same.
These technical roles describe interoperability. Joint development, support commitments, and promotion depend on separately agreed contributions. The open contract does not include free hosting; IAPKit and other providers set their own service terms.
Profile obligations · Conformance runner · Versioning and provider switching
Extend the contract together#
Start with the smallest connection your product needs. New store names, optional event members, and declared capabilities have defined extension points; existing consumers must handle them according to the versioning rules. The composition example adds a partner metadata string and verifies that the unchanged receiver preserves it. Adding metadata does not give it a shared business meaning automatically.
Propose shared behavior with a concrete use case, a runnable example, a rejection case, and its compatibility impact. Describe which implementers need to change. OpenIAP remains founder-led today; proposals and decisions are public, and IAPKit follows the same contract and checks as other implementations.
Start a public proposal · Review and decision process
A useful next contribution is a third provider or consumer with its own implementation. Keep the reference client and expected outcomes, record every configuration or adapter change, and publish the report with source revisions and limits. Participation does not require an OpenIAP account, central registry, or hosted validation service.
What a business delivers to an app team#
Ship the host adapter or backend endpoint, supported-store configuration, executable checks, and a short connection example. The app team chooses the services and expected behavior. Its AI can use your setup instructions, adapter, and executable checks to wire the connection and demonstrate the flow. Document what the team must decide and what a successful result looks like.
- Experience: product selection → OpenIAP purchase callback; show pending, canceled, failed, and fulfilled results.
- Commerce: published capabilities plus passing checks for every claimed profile/binding; store sandbox and account-isolation evidence separately.
- Data: signed event → durable inbox; prove retries, duplicates, malformed input, and unknown optional fields.
- Integrated platform: all the above for the roles it supplies, with one accountable owner for each state transition.
The local example proves request mapping, a fixture purchase-to-access flow, and event ingestion. It does not certify a paywall UI, real store adapter, revenue model, or arbitrary platform as compatible.