Core Concepts

Everything you need to know to build a subscription system with SubX, explained with examples. We'll use a note-taking app with a premium subscription as our running example.

The Big Picture

Products

A Product is something you actually sell on the app store (Apple/Google). Simply put, it's the "item that gets charged" on the store.

• Maps 1:1 to a store product ID (e.g. com.myapp.pro.monthly)
• Two types: subscription and non-subscription (one-time purchase)
• Register them in Dashboard → Products

Entitlements

An Entitlement is the "feature unlock" that activates when a user pays. Think of it as the on/off switch for premium features in your app code.

• Products and Entitlements have a many-to-many relationship — multiple products can unlock the same feature
• Your app code only needs to check Entitlements, not Products
• Create them in Dashboard → Entitlements and link Products

Offerings

An Offering is the "subscription menu" shown to your users. Like a restaurant menu, it groups the available options together.

• Turn on isCurrent to make this the default Offering the SDK loads
• Create multiple Offerings for different regions or experiments
• Manage them in Dashboard → Offerings

Packages

A Package is each individual item inside an Offering (menu). "Monthly Plan" and "Annual Plan" are each a Package.

• Use position to control display order (0 = top)
• A Package can have multiple Products linked to it
• Add them from the Offering detail screen

Paywalls

A Paywall is the "Subscribe now!" screen shown to users in your app — like YouTube Premium's signup screen or Netflix's plan selection page.

• One Paywall links to one Offering
• Config JSON controls the screen title, feature list, theme, etc. from the server
• Toggle isActive to enable or disable it

What goes in the Config JSON?

Any information your app needs to render the purchase screen. There's no fixed format — use whatever key-value pairs your app expects.

{
  "title": "Pro로 업그레이드하세요",
  "subtitle": "무제한 노트 + 클라우드 동기화",
  "features": [
    "무제한 노트 작성",
    "모든 기기 동기화",
    "오프라인 사용"
  ],
  "ctaText": "무료 체험 시작",
  "theme": "dark"
}

Experiments

An Experiment is an A/B test — run two versions at the same time and use real data to see which one performs better.

• Users are split into Control (current) and Treatment (experiment) groups
• Adjust weight to control the percentage of users in each group
• Variants can't be added/removed while running — to keep results reliable

Customers

A Customer is a user of your app. The SDK automatically creates anonymous users, and they become identified users once they log in.

• Created automatically when the SDK is initialized
• Link to your app's login to sync subscriptions across devices
• View subscription history in Dashboard → Customers

Subscriptions

A Subscription is a user's purchase history — when they started, whether payments are going through, if they cancelled, etc.

Full Flow: Putting It All Together

Here's the complete process of adding a premium subscription to a note-taking app:

Your app code just checks isEntitled("pro"). When you want to change pricing or add a promo product later, no app update needed.

Next Steps

• SDK Integration — Integrate the SubX SDK on iOS/Android.
• REST API — Use the API server-side.