iOS Subscriptions (Apple)

Overview

Adds Apple (StoreKit) subscriptions alongside Stripe. Backend becomes the single source of truth via:

• ASSN v2 webhook: POST /api/apple/assn
• Confirm purchase endpoint: POST /api/apple/confirm
• Unified entitlement check: see Entitlements doc

App Store Connect setup

• Set App Store Server Notifications V2 URL(s):
  • Production: https://<your-domain>/api/apple/assn
  • Sandbox: https://<your-domain>/api/apple/assn
• Ensure subscription product IDs exist (e.g. trial.weekly6.99, trial.monthly12.99, trial.annual99.99).

Endpoints

ASSN v2

• Method: POST
• URL: /api/apple/assn
• Body: Apple JWS envelope { signedPayload: string }
• Behavior: Decodes JWS payload, upserts apple_subscription (status: active|in_grace|expired). Full signature verification can be added.

Confirm purchase (client)

• Method: POST
• URL: /api/apple/confirm
• Body:

{
  "receipt": "<StoreKit2 signed transaction string or token>",
  "bundleId": "com.oneclick.tella",
  "environment": "Sandbox|Production",
  "productId": "optional"
}

• Returns: { "success": true, "isPro": boolean }
• Behavior: Decodes transaction if signed, upserts apple_subscription, and unlocks immediately; ASSN keeps it in sync.

Data model

apple_subscription stores: originalTransactionId, lastTransactionId, productId, status, expiresAt, gracePeriodExpiresAt, environment, bundleId.

iOS client notes

• After successful purchase, call /api/apple/confirm.
• For entitlement checks, call GET /api/entitlements/me.
• Recommended: set appAccountToken to link device user to server user.