SubscriptionFlow Mobile Stores API Reference (1.0.0)

1. Connect the stores under Settings > Marketplace > Integrations > Apple App Store / Google Play and map each store product (and Google base plan) to a SubscriptionFlow plan price.
2. Point the store notifications at SubscriptionFlow. Apple App Store Server Notifications V2 go to https://demo.subscriptionflow.com/webhook/apple; the Google Play RTDN Pub/Sub push subscription goes to https://demo.subscriptionflow.com/webhook/google-play (see Inbound store notifications).
3. Tag every purchase with an account token. Your backend issues one per customer with POST /mobile-stores/account-tokens and hands it to the app, which sets it as appAccountToken (iOS) or obfuscatedExternalAccountId (Android).
4. Report purchases. The app reports each purchase with POST /mobile-stores/client/purchases (the Flutter SDK subscriptionflow_iap does this for you); your backend can also register or restore a purchase for a customer with POST /mobile-stores/purchases.
5. Gate features on entitlements. Read GET /mobile-stores/client/entitlements in the app, or GET /mobile-stores/customers/{customer}/entitlements on your backend. Entitlements combine web, App Store and Google Play subscriptions.

SubscriptionFlow never trusts the request for product or price: every purchase is re-fetched from Apple or Google, and the store's answer decides product, amount, currency, status and expiry.

Requests and responses are JSON (Content-Type: application/json). All endpoints answer JSON, including errors.

Backend endpoints use the same REST API client as the rest of the SubscriptionFlow API. Create an API client (see the Client Credentials Guide) whose token carries the access-global-api scope, then request a token:

curl --location --request POST 'https://demo.subscriptionflow.com/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=your_client_id' \
--data-urlencode 'client_secret=your_client_secret' \
--data-urlencode 'grant_type=client_credentials'

Send it as Authorization: Bearer <access_token>. A missing, expired or invalid token answers 401 {"message": "Unauthenticated."}; a token without the access-global-api scope answers 403 {"message": "Invalid scope(s) provided."}. MCP agent tokens and customer-portal tokens never hold this scope.

Never ship these credentials in your app.

App endpoints take no OAuth token. They authenticate with the pair your backend received from POST /mobile-stores/account-tokens:

X-SF-Account-Token: c92b1774-af5d-4dc4-a375-cf377bfc118a
X-SF-Client-Secret: wjMQ6V90BaMwTVOXL7dYH8AKREmptMpFGE77V1jH5GdBojHt

The token must be active (not revoked) and the secret must match. Anything else, including a missing header, answers 401 {"status": false, "message": "Invalid account token or client secret"}. The customer is always the token's customer: the app can never act for another customer.

An account token is a SubscriptionFlow-issued UUID that stands for one customer. The app sets it on every store purchase (appAccountToken on iOS, obfuscatedExternalAccountId on Android), so purchases and notifications link to the right customer without exposing the customer ID.

• Issue with POST /mobile-stores/account-tokens. The first call for a customer answers 201 with account_token and a client_secret. The secret is returned only once (SubscriptionFlow stores a SHA-256 hash of it): keep it on your backend and pass it to the signed-in app.
• Reuse. Calling again while the customer has an active token answers 200 with the same account_token, client_secret: null and reused: true.
• Rotate. Send "rotate": true to revoke every active token of the customer and get a new pair (201).
• Revoke with DELETE /mobile-stores/account-tokens/{accountToken}. A revoked token can no longer authenticate the app, but it still identifies its customer: purchases tagged with it keep linking to that customer and can never be claimed by anyone else. Already linked purchases stay linked.

Require SubscriptionFlow-issued account tokens (a per-store setting, on by default for stores connected from 28 October 2026): when on, only issued tokens link purchases. When off, a raw SubscriptionFlow customer ID set as the account token is also accepted.

Every Mobile Stores endpoint answers JSON. Errors raised by the endpoints themselves have this shape:

{
  "status": false,
  "message": "purchase_token is required for Google Play",
  "errors": {
    "purchase_token": ["purchase_token is required for Google Play"]
  }
}

errors is present only for field validation failures (and for Customer not found on customer_id). message is always set; it is the first validation message when errors is present.

The app endpoint never reveals whether a purchase exists. Every ownership refusal, purchase unknown to the store, or production purchase sent to a Sandbox connection answers the same 409 This purchase cannot be linked to this account.

Idempotency. Registering or reporting the same purchase again is safe: SubscriptionFlow re-fetches the store state and re-syncs; each store charge and refund is booked at most once (unique per store transaction). Issuing a token without rotate is idempotent, revoking is idempotent, and usage reports are upserts. Retry 502, 503 and 429; do not retry other 4xx answers unchanged.

Limits are requests per minute.

Backend API endpoints share your account's REST API budget (sf_rest_ratelimit: 500 requests per minute per account) with the rest of the SubscriptionFlow REST API.

App / SDK API endpoints have their own limiter and never spend the REST budget:

Authenticated limits are per token, not per IP, so many devices behind one NAT are fine. Requests with a wrong token or secret only count against the per-IP bucket, so junk traffic cannot use up your account's app budget. Contact support to raise a limit.

A limited request answers 429 {"message": "Too Many Attempts."} with Retry-After, X-RateLimit-Limit and X-RateLimit-Remaining headers.

Each store connection has an Environment: Production or Sandbox. A purchase is mirrored only when its environment matches the connection, so TestFlight, App Review and Google licence-tester purchases never become revenue in a Production account.

App endpoint on a Production connection. Apple's reviewers and TestFlight users buy with sandbox accounts on your live app, and Google licence testers make test purchases. For such a purchase POST /mobile-stores/client/purchases verifies it (an Apple purchase unknown to Production is looked up in Apple's Sandbox with the same key; Google reports test purchases from the same API), applies the same ownership rules, and answers 200 with "sandbox": true, "linked": false, subscription_id: null and the entitlements of the mapped plan (each marked "sandbox": true; empty when the purchase is not active / in grace or has expired).

Nothing is recorded: no customer subscription, invoice, payment or link is created, the purchase is not acknowledged with Google, and the entitlements are not stored. They exist only in the app session (the SDK keeps them in memory): GET /mobile-stores/client/entitlements and your backend's entitlement reads do not include them.

Backend register API (POST /mobile-stores/purchases) keeps refusing a sandbox purchase on a Production connection (422 environment mismatch).

Sandbox connection. On a connection set to Sandbox, sandbox purchases are mirrored normally (the answer has "sandbox": false), and a production purchase is refused (backend 422, app 409).

Your backend links a store purchase to a SubscriptionFlow customer: use it when the app could not tag the purchase, or to restore purchases. Product and amount always come from the store.

Issue, reuse, rotate and revoke per-customer account tokens. See Account Tokens for the concepts.

Cross-channel entitlements for your backend. Define entitlement keys (for example pro) and the plans that grant them on the Entitlements tab of either store settings page. A customer holds an entitlement while any of their subscriptions on one of those plans entitles:

• App Store / Google Play subscriptions follow the store: active until the store expiry, grace until the store's grace end. On hold, paused, expired and revoked do not entitle, whatever SubscriptionFlow shows.
• Web subscriptions: Active or Trial (unless cancelled_at has passed), or Cancelled while cancelled_at is still ahead. A web subscription in dunning that is still Active keeps its entitlements.

Each entitlement names the grant that lasts longest (no end first, then the latest expires_at) in source, subscription_id and expires_at, and lists every granting subscription under grants. Times are UTC. expires_at: null means it renews / has no end.

There is no separate change feed: subscribe to SubscriptionFlow's existing subscription webhooks and read entitlements again when one arrives.

When a customer asks Apple for a refund, Apple may send a consumption request. With Answer Apple consumption requests turned on (Apple App Store settings, only with customer consent), SubscriptionFlow answers within Apple's 12-hour window. These endpoints let your backend add the usage values Apple asks for.

The app reads its own customer's entitlements with its account token pair. Same data as the backend Entitlements endpoint.

The app (or the Flutter SDK) reports a store purchase right after the store completes it. The SDK completes the store transaction only after a 200.

Inbound server-to-server notifications from Apple and Google. They are served on your tenant domain, not under /api/v1:

• POST https://demo.subscriptionflow.com/webhook/apple
• POST https://demo.subscriptionflow.com/webhook/google-play

Configure them in App Store Connect and Google Cloud Pub/Sub; you never call them yourself. The request is verified at receipt, stored, and processed on a queue: SubscriptionFlow re-fetches the authoritative state from the store API (the payload's order is never trusted), deduplicates notifications for 7 days (Apple notificationUUID, Pub/Sub messageId), and retries transient failures. A daily sync re-checks every live subscription to catch missed notifications.