Follow one purchase.

1. Install the contract#

npm install @hyodotdev/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 the verification and server credentials from your provider. A provider issues its own credentials; OpenIAP has no registration service. Each request sends one as Authorization: Bearer <credential>. 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_VERIFICATION_TOKEN: the verification credential
# COMMERCE_SERVER_TOKEN: the server credential

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 Apple evidence below as evidence.json; it follows the store chosen above. Replace the illustrative JWS with the StoreKit transaction JWS the app received. Your provider must be configured for that app and store environment.

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

curl --fail-with-body "$COMMERCE_BASE_URL/commerce/v1/purchases/verify" \
  -H "Authorization: Bearer $COMMERCE_VERIFICATION_TOKEN" \
  -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: Bearer $COMMERCE_SERVER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @binding.json

Continue after bound: true. For a store the provider integrates, a bound: false result intentionally does not distinguish unknown evidence from a purchase belonging to someone else; other stores fail with UNSUPPORTED_STORE instead. 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: Bearer $COMMERCE_SERVER_TOKEN" \
  --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 receiver steps 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. Without events, use bounded server reads at the points your application needs a current answer. SPEC.md §2.3 defines when a subscription grants access.

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.

jq -n --arg userId "$COMMERCE_USER_ID" '{userId: $userId}' > erasure.json

curl --fail-with-body "$COMMERCE_BASE_URL/commerce/v1/users/erase" \
  -H "Authorization: Bearer $COMMERCE_SERVER_TOKEN" \
  -H 'Content-Type: application/json' \
  --data-binary @erasure.json

A 202 with accepted: true acknowledges the request. When the answer carries a job status, send the same request again to read the job's progress: repeating it is safe and reports the current job. The provider's cleanup is finished at completed.

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

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, this section is all you need. The purchase and access operations above 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.

npm install

npm run demo:consumer