A vendor-neutral specification for the server side of in-app purchases.
OpenIAP normalizes the client-side purchase API across stores. This normalizes the server side: one commerce vocabulary, one portable operation surface with REST and GraphQL bindings, one event envelope, one webhook contract — so a backend or an analytics pipeline can verify purchases, read entitlements, and handle renewals, refunds, and entitlement changes from Apple, Google, Meta Horizon, and Amazon without parsing any store-native payload, and can replace the provider behind those calls without rewriting the integration.
Nothing in this contract routes through infrastructure the OpenIAP project operates. Two parties exchange events directly, using a secret they share between themselves, and validate offline. The project distributes the contract; it does not sit in the path of anyone's commerce.
A paywall specialist can supply the experience, a commerce service the purchase and access decisions, and an analytics platform the event processing. An integrated platform can supply several roles. Explore the role map and AI integration brief to connect your product to apps using OpenIAP. These product roles do not add protocol profiles or a universal paywall API.
npm install @hyodotdev/openiap-commerce-protocolOr use pnpm add, yarn add, or bun add with the same package name.
Give your AI the installed package's SPEC.md, DESIGN.md, and generated/
artifacts. The package supplies the contract; your AI implements the backend.
- See what AI built: the recorded walkthrough shows a real local HTTP + SQLite backend in seven milestones, with captured responses. The IAPKit comparison explains what was tested. Give the build brief to your AI to build the same flow in your own stack.
- Integrate your backend: Use a provider walks through discovery, verification, account binding, and entitlement reads.
- Build a provider: Build with AI provides the brief, runnable example, and next implementation steps. DESIGN.md §5 contains the architecture blueprint, storage keys, transaction boundaries, and recovery design.
- Try the contract locally: from the repository root, run
bun install, thencd specs/commerce-protocol && bun run quickstart. The development walkthrough uses the in-memory mock, checks authorization and binding behavior, and runs REST/GraphQL conformance. It uses fixture evidence, opens no HTTP server, and does not validate real store purchases. Its Ajv and GraphQL dependencies come from this package's development setup.
DESIGN.md explains why the boundaries sit where they do. It is
background, not normative: where the two disagree, SPEC.md is right. It is
also published as a PDF at
https://www.openiap.dev/commerce-protocol-rationale.pdf.
The contract sits between the stores and everything downstream of a backend:
flowchart TB
stores["Apple / Google<br/>/ Meta / Amazon<br/>the stores"]
backend["A backend that<br/>implements this spec<br/>IAPKit, another<br/>provider, or the<br/>adopter's own<br/>— in any language<br/><br/>verify → normalize<br/>→ lifecycle → entitle"]
app["shipped application<br/>verification role (§5)"]
server["the adopter's backend<br/>server role (§5)"]
consumers["any consumer<br/>data pipeline<br/>/ CRM / analytics"]
stores -->|" store-native <br/> notifications and APIs "| backend
app -->|" verifyPurchase, <br/> providerCapabilities <br/> (§4.1, §4.6) <br/> over REST (§6) or <br/> GraphQL (§7) "| backend
server -->|" those, plus <br/> subscriptionStatus, <br/> entitlements, <br/> bindPurchase, <br/> eraseUser (§4.2–§4.5) <br/> server role only <br/> — never a shipped app "| backend
backend -->|" OpenIAP Commerce <br/> Protocol events (§9) "| consumers
Review only the authored surfaces, in this order:
SPEC.md— behavior, operations, bindings, lifecycle, transport, and compatibility.schema/— the authored contract layers: wire structure, the operation surface, and validation directives.generated/commerce-protocol.graphqlis their generated single-file assembly (also exported at the package path@hyodotdev/openiap-commerce-protocol/commerce-protocol.graphql).examples/— representative documents and store mappings.vectors/signatures.json— hand-authored cryptographic truth cases.conformance/— the portable runner and its independent mock provider.
Ignore generated/ during a human review. It is compiler output, kept only for
validators and drift checks.
| Path | Contents |
|---|---|
schema/ |
Authored type, operation, and validation contract layers — edit these |
SPEC.md |
Normative meaning, operations, bindings, transport, and compatibility rules |
DESIGN.md |
Why the boundaries sit where they do — background, never normative |
generated/ |
Compiler output: schemas, binding manifests, OpenAPI, and vectors |
examples/ |
Canonical documents that must validate |
vectors/signatures.json |
Signature vectors every implementation must reproduce |
conformance/ |
Portable conformance runner plus an IAPKit-free mock provider |
src/index.mjs |
Runtime access to the generated schemas and their derived constants |
The schema/ layers govern wire structure. Their custom directives retain
patterns, bounds, maps, open objects, and conditional rules that standard SDL
cannot express. bun run build compiles that source into the JSON Schemas a Go,
Python, or other backend executes against incoming webhook bodies. SPEC.md
governs meaning and transport.
Do not add this SDL to specs/client/schema-files.mjs. specs/client owns the
client purchase API and the SDK types compiled from it; this file independently
owns the server-to-server commerce contract. Its Query and Mutation types are
the portable server operation surface — compiled into the REST and GraphQL
bindings, never into client SDK types — and it defines no Subscription root:
the operation surface is bounded request/response by rule.
An endpoint you register receives one JSON event per request. Verify the
signature — SPEC.md §9.4.2 states the rule and vectors/signatures.json pins
it — then handle the event; SPEC.md §9.5 walks a consumer end to end.
Three rules that are easy to get wrong, all specified in detail in SPEC.md:
- Sign the bytes you received. Re-serializing the JSON before verifying changes key order and whitespace, and the signature will not match.
- Read
subscription.active, notstate. A canceled subscription keeps access until its paid period ends —subscription.canceledmeans auto-renew was turned off, not that access was revoked. - A missing amount means unknown. It never means zero.
Start with the provider's capability descriptor. Every conforming provider
supports discovery; its declared profiles determine which purchase, status,
entitlement, binding, and erasure operations it supports. Check those profiles
before calling an operation. REST and GraphQL bindings share one error-code
space. SPEC.md §4–§8 define the surface and authorization rules.
Point the portable runner in conformance/ at a test instance of your
provider; SPEC.md §11.2 has the script.
The runner is offline, needs no hosted service, and imports no implementation;
supply the Ajv 2020 class yourself, since the published runtime carries zero
dependencies. It certifies the transport contract — never real store receipt
validity (SPEC.md §11.3). A provider that declares the events profile must
also pass an eventsAdapter covering the full EventsAdapter surface
(conformance/index.d.ts); a signing-only adapter fails.
From a repository clone (the npm package does not ship scripts/ or test/):
bun install # at the repository root
cd specs/commerce-protocol && bun run testThe suite recompiles every schema and binding artifact, validates every
example, checks that each rejection case is actually rejected, reproduces
every signature vector using an implementation written only from SPEC.md,
and certifies an independent mock provider on both bindings.
OpenIAP Commerce Protocol ← this package: the server-side contract
│
┌──────────────┼──────────────┐
│ │ │
IAPKit vendor backend custom backend
(reference)
│ │ │
└──────────────┼──────────────┘
↓
normalized commerce events
↓
┌──────────────┼──────────────┐
│ │ │
SaaS analytics enterprise
No box in that diagram is required to be operated by the OpenIAP project. An adopter may self-host IAPKit, use a hosted conforming provider, or implement the contract in the backend they already have — and a consumer supports the specification, so any of the three can feed it.
Implements protocol version 1.0. The event vocabulary,
envelope, webhook contract, operation surface, REST and GraphQL bindings, and
portable conformance runner are implemented and tested. SPEC.md §14 lists
what is deliberately not in this version.
MIT