Follow one purchase.

Alice buys Premium in your app. Follow her purchase from the store’s payment screen to the moment she can open paid content.

At each step, compare two implementations: openiap-commerce-protocol-example makes the flow visible with a local dashboard and fictional purchases; IAPKit connects the same contract to store services. Follow the behavior first, then open either implementation’s code when you need it.

Apple and Google subscription changes arrive through store notifications. Amazon and Horizon access is rechecked with the store when your backend requests it. Choose your store below to follow the matching path.

.commerce-journey-steps, .commerce-journey-content, .commerce-journey-controls { display: none; }Read the purchase flow in order below. Enable JavaScript to use the step navigator.

1. Alice chooses Premium.

Alice chooses Premium on your paywall. Your app opens Apple’s purchase screen through its OpenIAP client library. A successful purchase gives your backend the evidence it needs to ask the store for verification.

Payment returned. Premium is still locked. The app sends the evidence to your backend using Alice’s signed-in session. A pending, canceled, or failed purchase creates no new access.

Purchase evidence: The store’s record of the purchase. It is something the backend can check; it is not proof of which app account owns it.

Where the store result goes

Run the flow locally

openiap-commerce-protocol-example

The purchase mapper converts Apple, Google, Amazon, and Horizon client results into verification input on your backend. Its demo checks the mapping without making a store purchase.

Read code: toVerifyPurchaseInput

See the service implementation

IAPKit

IAPKit receives that store evidence through verifyPurchase. The paywall, store purchase screen, and app login stay with your app; IAPKit does not replace them.

Read code: verifyPurchase

How to check this behavior

Example. runBridgeDemo checks all four store mappings and requires a separate store identity for Amazon and Horizon. Run npm run demo:bridge. Inspect reference

IAPKit. Route tests cover evidence parsing and errors with mocked store calls; they do not perform a mobile purchase. Inspect reference

How verification works

2. Check the purchase with the store.

Your backend asks the commerce provider to check the evidence. The provider is the service responsible for purchase verification and access records. It can be IAPKit, another compatible service, or a backend you run.

The purchase is valid. Premium is still locked. A successful check answers “is this evidence valid?” It does not decide who gets access. If verification is unavailable, retry according to your policy; an outage is not a new purchase or a revocation.

Verification: Checking store evidence. The API call is verifyPurchase; its isValid result is separate from the user’s access.

Same question: is the evidence valid?

Run the flow locally

openiap-commerce-protocol-example

verifyFixture recognizes one fictional purchase. A valid result saves it in SQLite with no user attached. You can watch Alice’s access stay locked after verification.

Read code: verifyPurchase

See the service implementation

IAPKit

The handler sends evidence to the Apple, Google, Meta, or Amazon verifier and returns the same isValid answer. Store-specific work stays behind this call.

Read code: verifyPurchaseVerdict

How to check this behavior

Example. The Verify step checks isValid and confirms that Alice still has no access. Run npm test. Inspect reference

IAPKit. The route suite checks unreachable verification and retry behavior using mocked store I/O. Inspect reference

Verification reference

3. This purchase belongs to Alice.

Your backend knows who signed in and checks whether that person may claim the purchase. It asks the provider to associate the verified purchase with Alice’s account. This association is called binding.

Alice owns the purchase. Now read her access. Bob cannot take the same purchase by submitting Alice’s receipt. A failed binding stops this attempt. Repeating Alice’s successful request leaves the same owner in place.

Authentication: Your app login identifies Alice. A separate server credential lets your backend call the provider. The provider credential never replaces your app’s login.

Same owner after a retry

Run the flow locally

openiap-commerce-protocol-example

One SQLite transaction assigns the unowned purchase to Alice and queues the access event. Repeating Alice’s request succeeds; Bob’s conflicting claim returns bound: false.

Read code: bindPurchase

See the service implementation

IAPKit

The protocol handler calls bindUserAsServer. Convex checks the project’s server credential and records ownership without moving a purchase already owned by another user.

Read code: bindUserAsServer

How to check this behavior

Example. The Bind step repeats Alice’s request and rejects Bob’s claim. Run npm test. Inspect reference

IAPKit. Binding tests cover repeated and conflicting claims against the subscription mutation handlers. Inspect reference

Who may make each request

4. Ask what Alice can use now.

Your backend reads Alice’s current entitlements: the products she is allowed to use. If Premium is in that answer, your backend lets her open the paid content. It records fulfillment before the app finishes the store transaction.

Alice can use Premium. Access is a current answer, not a permanent flag. An empty product list grants nothing. Respect expiry and freshness when caching; a failed read is not a successful access decision.

Entitlements: What this user may access now. Subscription status explains the subscription; entitlements answer which products it currently unlocks.

Same access rule, different storage

Run the flow locally

openiap-commerce-protocol-example

isEntitled reads the subscription state and expiry. SQLite holds the records; entitlements returns only products Alice can use now. Turning renewal off does not end paid access.

Read code: isEntitled

See the service implementation

IAPKit

isEntitledAt applies the same rule to Convex records. entitlementsV2 reads the current time and returns allowed products without exposing store purchase tokens.

Read code: isEntitledAt

How to check this behavior

Example. The state checks test before, at, and after expiry with a controlled clock. Run npm test. Inspect reference

IAPKit. Account-read tests check token omission, server authorization, and time advancing past expiry. Inspect reference

Access reference

5. Cancellation keeps the paid time.

Alice turns off renewal. She keeps Premium until the end of her paid period. When that deadline arrives, access ends—even if a store notification is late. Your backend reads the current answer when it needs to authorize her.

Renewal off → Premium stays open → expiry locks it. Events travel between servers. Your receiver checks the signature and saves each event once before acknowledging it. Retries must not repeat fulfillment.

Webhook: An HTTP message the provider sends to your backend when something changes. A signature lets your backend check who sent it and whether it was altered.

Retries keep one inbox entry

Run the flow locally

openiap-commerce-protocol-example

A local worker signs and retries events. The included receiver verifies the signature and saves each event once in a separate SQLite inbox. Use it to understand both ends of delivery.

Read code: deliver / createReceiver

See the service implementation

IAPKit

The delivery worker sends signed events to registered backend HTTPS endpoints and records attempts. Your receiver owns duplicate handling; the example shows how to build that side.

Read code: deliverPendingEventsHandler

How to check this behavior

Example. Checks cover signatures, retries, tampering, and reopening the inbox. Run npm test or npm run demo:consumer. Inspect reference

IAPKit. Worker tests check signed requests, transport failures, and destination validation with test I/O. Inspect reference

Events and delivery reference

6. Alice deletes her account.

Your backend disables Alice’s session and removes her saved event copies. It then asks every commerce provider holding her records to erase her identity. The example completes this in SQLite; IAPKit completes a queued job in Convex.

Identity removed. Old requests cannot restore the account. Keep unfinished deletion requests until the provider confirms completion. Your receiver must discard late events for the deleted account, including after restart. This removes account identity; it does not cancel the store subscription.

Account erasure: Removing the link to the app user from provider records and copies held by your services. An accepted job can still be queued; wait for completed before considering provider cleanup finished.

Delete the account in both implementations

Run the flow locally

openiap-commerce-protocol-example

Step 7 removes identity from purchases and event records atomically. The app erases delivered copies and remembers the deletion so late signed events cannot restore the user.

Read code: eraseUser

See the service implementation

IAPKit

eraseUser starts a project-scoped job. The worker removes identity from purchases, subscriptions, and events in batches, waiting for claimed deliveries before cleaning those events.

Read code: drainSubscriptionUserErasurePage

How to check this behavior

Example. Run bun verify-erasure.mjs. It checks active-account erasure, in-flight delivery, repeated jobs, late events, and restart. Inspect reference

IAPKit. Erasure request tests cover server authorization and repeated requests, including already completed jobs. Inspect reference

Erasure reference

Step 1 of 6

Alice chooses Premium.

Your appAlice chooses Premium

AppleHandles the payment

Your appReceives purchase evidence

Payment returned. Premium is still locked.

The app sends the evidence to your backend using Alice’s signed-in session. A pending, canceled, or failed purchase creates no new access.

Where the store result goes

Run the flow locally

openiap-commerce-protocol-example

The purchase mapper converts Apple, Google, Amazon, and Horizon client results into verification input on your backend. Its demo checks the mapping without making a store purchase.

Read code: toVerifyPurchaseInput

See the service implementation

IAPKit

IAPKit receives that store evidence through verifyPurchase. The paywall, store purchase screen, and app login stay with your app; IAPKit does not replace them.

Read code: verifyPurchase

How to check this behavior

Example. runBridgeDemo checks all four store mappings and requires a separate store identity for Amazon and Horizon. Run npm run demo:bridge. Inspect reference

IAPKit. Route tests cover evidence parsing and errors with mocked store calls; they do not perform a mobile purchase. Inspect reference

Next: Verify

See the same app switch between the example and IAPKit →

Ready to build? Choose your services and build it →

Implementation reference: requests and receiver setup

Use these details when wiring a backend or checking your AI’s code.

Receive subscription changes#

Connect an existing backend with the ready receiver. It verifies the signature, validates the event, and saves it once in SQLite. You do not need to build a commerce provider or a store adapter.

If your service only consumes events, start here. The purchase and access operations below belong to the app backend and its chosen provider; your service can keep its existing backend.

The example repository includes the receiver and executable checks. AI can reuse it to demonstrate signed delivery, retries, tamper rejection, and preserved inbox entries after reopening storage.

Run the receiver example locally

Clone the repository, install Bun for its runtime, then install dependencies and run the demo. This fixture check requires no credentials or external services.

Use your favorite package manager.

npm install

npm run demo:consumer

Recorded results and payloads

Connect the receiver to your provider

Set COMMERCE_WEBHOOK_SECRET to your provider’s signing secret, then run npm run consumer. The ready endpoint is http://127.0.0.1:5182/webhooks/commerce. Put it behind your HTTPS reverse proxy, forwarding the exact body bytes to that local address, and register the HTTPS URL with your provider. The receiver accepts the public Host header forwarded by the proxy; its signature check authenticates the sender.

Use one emitter/project and signing key per receiver database. consumer.sqlite is the durable inbox; set COMMERCE_INBOX_PATH for your persistent storage path. To embed the same Fetch-compatible handler in your server, use createReceiver from webhooks.mjs.

The inbox preserves the signed event for your existing processing pipeline. Transaction and price fields are optional; a missing price is unknown. Each lifecycle event is not necessarily a new charge. Keep financial calculations in your business logic.

1. Install the contract#

Use your favorite package manager.

npm install openiap-commerce-protocol

The package gives your backend the contract, schemas, and conformance tools. Obtain a compatible provider endpoint and credentials separately.

To explore first, open the recorded purchase flow, or run the reference dashboard. To implement your own provider, give your AI the build brief.

2. Connect to a provider#

Obtain the base URL, supported store configuration, and Authorization header values from your provider. A provider issues its own credentials; OpenIAP has no registration service. Keep the server credential in your backend. These shell examples assume curl and jq.

export COMMERCE_BASE_URL='https://your-provider.example'
# Set these through your local secret manager or environment.
# COMMERCE_VERIFY_AUTH: complete Authorization header value for verification
# COMMERCE_SERVER_AUTH: complete Authorization header value for the server role

curl --fail-with-body "$COMMERCE_BASE_URL/commerce/v1/capabilities"

Inspect profiles, bindings, and the selected store’s implementation support. This flow needs verification, accountLifecycle, entitlements, and rest at compatible major versions. An events-only descriptor does not establish operation support. See capabilities for the full descriptor.

3. Verify, bind, and read access#

Save the following shape as evidence.json. Replace its illustrative JWS with a real StoreKit transaction JWS from the app. For Google, use { "store": "google", "google": { "purchaseToken": "…" } }. Your provider must be configured for that app and store environment.

json

{
  "store": "apple",
  "apple": {
    "jws": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0cmFuc2FjdGlvbklkIjoiMjAwMDAwMDEyMzQ1Njc4OSIsInByb2R1Y3RJZCI6InByZW1pdW0ubW9udGhseSJ9.MEUCIQDkQmFrb2Zha2VzaWduYXR1cmVmb3JleGFtcGxlAiBkb2N1bWVudG9ubHlmYWtlc2lnbmF0dXJldmFsdWU"
  }
}

curl --fail-with-body "$COMMERCE_BASE_URL/commerce/v1/purchases/verify" \
  -H "Authorization: $COMMERCE_VERIFY_AUTH" \
  -H 'Content-Type: application/json' \
  --data-binary @evidence.json

A successful response carries isValid. A store rejection is still a successful operation with isValid: false. VERIFICATION_FAILED means no verdict was obtained; retry according to your failure policy. Neither a verdict nor its advisory state identifies the app user or answers their current access.

Your backend authenticates the user and checks that it may associate this purchase with them. Select COMMERCE_USER_ID from that session and ownership policy. A user ID submitted by the app and possession of a receipt are not sufficient authorization.

# Run on your backend; COMMERCE_USER_ID is selected by your authenticated handler.
jq --arg userId "$COMMERCE_USER_ID" '. + {userId: $userId}' \
  evidence.json > binding.json

curl --fail-with-body "$COMMERCE_BASE_URL/commerce/v1/purchases/bind" \
  -H "Authorization: $COMMERCE_SERVER_AUTH" \
  -H 'Content-Type: application/json' \
  --data-binary @binding.json

Continue after bound: true. A bound: falseresult intentionally does not distinguish unknown evidence from a purchase belonging to someone else. Do not transfer the binding or grant access on that result; use your provider’s recovery process. The association can remain bound even when the subscription is expired.

curl --fail-with-body --get "$COMMERCE_BASE_URL/commerce/v1/entitlements" \
  -H "Authorization: $COMMERCE_SERVER_AUTH" \
  --data-urlencode "userId=$COMMERCE_USER_ID"

Gate product-specific features on membership in productIds. An empty list is a complete answer with no current access. An operation error is not an empty list. The subscriptions array contains the tokenless records supporting that answer. For a simple “any active subscription?” check, use subscriptionStatus.active.

4. Handle changes after purchase#

If the provider declares events, register an HTTPS backend destination using its management interface and exchange a webhook secret. Destination registration is provider-specific. Follow the backend architecture to authenticate and persist each delivery before acknowledging it.

Use events to trigger an authoritative entitlement refresh when you cannot safely correlate purchases, especially across multiple subscriptions or product changes. A cancellation disables renewal; it does not automatically remove the remaining paid access. Without events, use bounded server reads at the points your application needs a current answer.

When an authenticated user deletes their account, call eraseUser from your backend. The provider erases its own identity records; arrange erasure separately for copies already delivered to your backend and connected services.

Continue with the operation reference, GraphQL binding, or provider implementation guide.