ZeroSettle StoreKit API

openapi: 3.2.0
info:
  title: ZeroSettle IAP Cancel Flow Store Kit API
  description: The ZeroSettle IAP API powers the iOS, Android, and Flutter SDKs. It enables product catalog fetching, web checkout, entitlement management, subscription lifecycle operations, and StoreKit transaction syncing. All endpoints are authenticated via the `X-ZeroSettle-Key` header.
  version: 1.0.0
  contact:
    name: ZeroSettle Support
    email: support@zerosettle.io
    url: https://zerosettle.io
servers:
- url: https://api.zerosettle.io/v1
  description: Production
security:
- ApiKeyAuth: []
tags:
- name: StoreKit
  description: Sync and query StoreKit transactions
paths:
  /iap/storekit-transactions:
    post:
      operationId: syncStorekitTransaction
      summary: Sync StoreKit Transaction
      description: 'Forwards a StoreKit 2 JWS (JSON Web Signature) transaction to ZeroSettle for verification and recording. The backend verifies the JWS against Apple''s root certificate chain, creates a `Transaction` and `Entitlement`, and returns success. The SDK should call `transaction.finish()` only after receiving a success response.


        SDK 1.3+ additionally forwards `will_auto_renew` (pulled from `Product.SubscriptionInfo.RenewalInfo.willAutoRenew`) on every sync. The backend diffs this against the stored entitlement state and emits `CANCELLED` / `REACTIVATED` events when the flag flips, so auto-renew state stays accurate even in deployments without App Store Server Notifications (ASSN) v2 configured.'
      tags:
      - StoreKit
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - jws_representation
              - user_id
              properties:
                jws_representation:
                  type: string
                  description: The StoreKit 2 transaction's JWS representation string.
                user_id:
                  type: string
                  description: The user's external ID.
                will_auto_renew:
                  type: boolean
                  description: Optional (SDK 1.3+). The current `willAutoRenew` value from StoreKit's `Product.SubscriptionInfo.RenewalInfo` for the subscription this JWS belongs to. When provided, the backend compares it against the stored entitlement and emits `CANCELLED` (true→false) or `REACTIVATED` (false→true) events. Omit the field for non-subscription syncs or older SDKs; behaviour is unchanged when missing.
                renewal_state:
                  type: string
                  description: 'Optional (SDK 1.3+, reserved). Mirror of StoreKit''s `Product.SubscriptionInfo.RenewalState` for future use. Accepted but not currently acted on. Typical values: `subscribed`, `expired`, `in_billing_retry_period`, `in_grace_period`, `revoked`.'
                  enum:
                  - subscribed
                  - expired
                  - in_billing_retry_period
                  - in_grace_period
                  - revoked
      responses:
        '200':
          description: Transaction synced successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /iap/storekit-subscription-status:
    get:
      operationId: getStorekitSubscriptionStatus
      summary: Get StoreKit Subscription Status
      description: Returns the current status of a StoreKit subscription by its original transaction ID. Useful for checking renewal state and expiry. The response includes normalized `is_active` and `auto_renew_enabled` booleans (SDK 1.2+); prefer these over the raw `status`/`auto_renew_status` fields for canonical access decisions.
      tags:
      - StoreKit
      parameters:
      - name: original_transaction_id
        in: query
        required: true
        description: The StoreKit original transaction ID for the subscription.
        schema:
          type: string
      responses:
        '200':
          description: Subscription status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorekitSubscriptionStatus'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: Invalid request -- missing or malformed parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    StorekitSubscriptionStatus:
      type: object
      description: Status of a StoreKit subscription. Prefer the normalized `is_active` and `auto_renew_enabled` booleans for canonical access decisions; `status` and `auto_renew_status` are diagnostic fields that mirror the raw Apple payload.
      required:
      - is_active
      - auto_renew_enabled
      properties:
        status:
          type: integer
          description: 'Diagnostic only — SDK-collapsed Apple status: 1 (active) or 2 (not active). Prefer `is_active` for access decisions.'
        auto_renew_status:
          type: integer
          description: Diagnostic only — raw Apple `autoRenewStatus` integer (0 = off, 1 = on). Prefer `auto_renew_enabled` for canonical use.
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
          description: When the subscription expires or renews.
        is_active:
          type: boolean
          description: Canonical active-entitlement flag. `true` when the Apple status code represents active access (active, grace period, or billing retry with access). Derived server-side from `apple_status` — use this instead of interpreting `status` yourself.
        auto_renew_enabled:
          type: boolean
          description: Canonical auto-renew flag. Equivalent to `auto_renew_status == 1`, exposed as a boolean for consistency with the rest of the API.
    Error:
      type: object
      description: Error response.
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code (not always present).
      required:
      - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-ZeroSettle-Key
      description: Your publishable API key. Use `zs_pk_test_*` for sandbox or `zs_pk_live_*` for production.