Core Concepts

This guide explains the fundamental concepts of Iaptic and how they work together.

Overview

Iaptic is a unified in-app purchase validation and subscription management service that works across multiple platforms:

• Apple App Store
• Google Play Store
• Microsoft Store
• Braintree
• Stripe

Key Concepts

Receipts

A receipt is a platform-specific proof of purchase. Iaptic validates the receipts sent by your app using platform APIs to:

• Verify authenticity of the purchases
• Extract up-to-date information about the purchase(s) it contains
• Track subscription status
• Maintain a collection of purchases for a given customer

Apple receipts contain information about all purchases for a given customer. These receipt is refered to as the application receipt. Other platforms typically provide one receipt per purchase.

Purchases

A purchase represents a commercial relationship between a customer and your app. Key characteristics:

• Subscriptions: Single purchase with multiple transactions (renewals)
• Consumables: Single purchase with one transaction
• Platform differences:
  • Apple: Original transaction ID as purchase ID
  • Google: Order ID as purchase ID
  • Stripe: Subscription ID as purchase ID
  • All platforms: Searchable in dashboard by these IDs

Subscription Example:

flowchart LR
    Purchase(Purchase: SUB_123) --> Transaction1(Transaction: Month 1)
    Purchase --> Transaction2(Transaction: Month 2)
    Purchase --> Transaction3(Transaction: Month 3)

Each purchase has:

• A unique purchase identifier
• A transaction identifier (which is the last transaction in the purchase)
• A product identifier
• A purchase date

For subscriptions, the purchase date is the start date of the subscription. Subscription purchases also contain a lastRenewalDate, which is the date of the most recent renewal, and a expirationDate, which is the date the subscription will expire (or renew).

See API doc for Purchase for more details.

The Subscriptions Overview page has more details on how subscriptions work.

Entitlements

Entitlements are the permissions granted to a customer for a given purchase. They should be used to unlock content, features, or services in your app.

A list of customers entitled to a purchase is associated with the purchase, in the entitledUsers field. When a purchase is updated, a webhook is sent to your server for each customer currently or previously entitled to the purchase.

For more details, see:

• Entitlements strategies.
• API doc for Purchase.

Purchases vs Receipts vs Transactions

Entitlements are associated with individual purchases, not receipts or transactions. A single receipt can contain multiple purchases, and each purchase follows the configured entitlement strategy independently.

flowchart TB
    Receipt -->|contains 1+| Purchase
    Purchase -->|has 1+| Transaction
    Purchase -->|entitled to| User
    
    style Receipt fill:#e6f3ff,stroke:#333
    style Purchase fill:#ffe6e6,stroke:#333
    style Transaction fill:#e6ffe6,stroke:#333
    style User fill:#f0e6ff,stroke:#333

Key Relationships:

• 📥 One Receipt can contain multiple Purchases
• 🔄 One Purchase (or subscription, in that context) can have multiple Transactions (renewals)
• 👤 Purchases are linked to users based on entitlement strategy
• 📱 Platform determines receipt structure:
  • iOS: All purchases in one receipt
  • Android: Typically one purchase per receipt
  • Subscriptions: Multiple transactions per purchase
  • Consumables: Single transaction per purchase

Webhooks

Webhooks are how Iaptic notifies your server about:

• New purchases
• Subscription renewals
• Status changes and other events (cancellation, expiration, refunds, etc.)

Use them to keep your server in sync (update subscription status, unlock content, deliver virtual goods, etc.)

See Webhook Reference for more details.

Events

Events are records of everything that happens in your app:

• Receipt validations
• Webhook deliveries
• Server notifications sent by the platforms

Data Flow

graph LR
    A[App] -->|Receipt| B[Iaptic]
    B -->|Validation| C[Store API]
    F[Store Server] -->|Notification| B
    C -->|Response| B
    B -->|Webhook| D[Your Server]
    B -->|Events| E[Dashboard]

Next Steps

• First integration
• Set up your first app
• Implement receipt validation
• View the API reference

Need help? Contact our support team.