Skip to content

Latest commit

 

History

History

commerce-protocol

README.md

OpenIAP Commerce Protocol

npm

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.

Read the specification →

Choose your role

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.

Start implementing

npm install @hyodotdev/openiap-commerce-protocol

Or 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, then cd 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 -->|"&nbsp;store-native&nbsp;<br/>&nbsp;notifications and APIs&nbsp;"| backend
  app -->|"&nbsp;verifyPurchase,&nbsp;<br/>&nbsp;providerCapabilities&nbsp;<br/>&nbsp;(§4.1, §4.6)&nbsp;<br/>&nbsp;over REST (§6) or&nbsp;<br/>&nbsp;GraphQL (§7)&nbsp;"| backend
  server -->|"&nbsp;those, plus&nbsp;<br/>&nbsp;subscriptionStatus,&nbsp;<br/>&nbsp;entitlements,&nbsp;<br/>&nbsp;bindPurchase,&nbsp;<br/>&nbsp;eraseUser (§4.2–§4.5)&nbsp;<br/>&nbsp;server role only&nbsp;<br/>&nbsp;— never a shipped app&nbsp;"| backend
  backend -->|"&nbsp;OpenIAP Commerce&nbsp;<br/>&nbsp;Protocol events (§9)&nbsp;"| consumers
Loading

Reviewing a change

Review only the authored surfaces, in this order:

  1. SPEC.md — behavior, operations, bindings, lifecycle, transport, and compatibility.
  2. schema/ — the authored contract layers: wire structure, the operation surface, and validation directives. generated/commerce-protocol.graphql is their generated single-file assembly (also exported at the package path @hyodotdev/openiap-commerce-protocol/commerce-protocol.graphql).
  3. examples/ — representative documents and store mappings.
  4. vectors/signatures.json — hand-authored cryptographic truth cases.
  5. 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.

What ships here

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.

Receiving events

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, not state. A canceled subscription keeps access until its paid period ends — subscription.canceled means auto-renew was turned off, not that access was revoked.
  • A missing amount means unknown. It never means zero.

Calling a provider

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.

Certifying a provider

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.

Validating

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 test

The 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.

Relationship to the rest of OpenIAP

       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.

Status

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.

License

MIT