Manage subscriptions on iOSPrivate preview
Accept recurring payments and manage entitlements with the BillingSDK for iOS.
Accept subscription payments, let customers manage their subscriptions and manage Entitlements directly in your iOS app with the BillingSDK for iOS. The SDK provides prebuilt UI components to display buy buttons, present the customer portal and check entitlements to gate premium features.
Before you begin
To use the BillingSDK for iOS, you’ll need:
- A back end server to create Customer Sessions
- A Stripe account with access to the private preview
- iOS 15.0 or later and macOS 12.0 or later
- Xcode 15.0 or later
What you’ll build
This guide shows you how to:
- Set up a server endpoint to create Customer Sessions
- Install and configure the BillingSDK for iOS
- Display buy buttons for subscription purchases
- Check entitlements to gate premium features
- Present the customer portal for subscription management
- Handle errors and manage session state
You can find a complete example app in the BillingSDK for iOS repository.
Create a server endpoint that generates Customer Sessions for authenticated users. These sessions securely authenticate your iOS app with Stripe’s billing APIs.
Create a customer session endpoint
The endpoint needs to:
- Verify that the user is authenticated
- Create or retrieve the Stripe Customer ID for the user
- Create a Customer Session with the required components enabled
- Return the session details to your app
Here’s an example implementation:
Response format
The endpoint must return these fields for successful authentication:
| Field | Type | Description |
|---|---|---|
clientSecret | string | The Customer Session secret used to authenticate the SDK |
expiresAt | number | Expiry timestamp in seconds since epoch |
customer | string | The Stripe Customer ID |
When authentication fails, return HTTP 401 to trigger the SDK’s unauthenticated state.
The BillingSDK for iOS provides a native iOS experience for subscription management and feature access control.
Add the SDK to your project
During private preview, install the BillingSDK package:
- Open your project in Xcode
- Select File → Add Package Dependencies
- Type
https://github.into the Search or Enter Package URL fieldcom/stripe-samples/billing-ios-sdk - Select
BillingSDKand click Add Package
Configure the SDK
Initialise the SDK in a shared class to handle the BillingSDK setup and authentication:
Note
The SDK handles thread safety internally – you can safely call its methods from any thread.
Set up the Customer Session provider
Add the authentication method to your billing manager:
Note
The BillingSDK automatically calls your session provider whenever it needs to authenticate with Stripe. When the provider returns nil, the SDK enters an unauthenticated state.
Buy buttons provide a prebuilt UI element to let customers purchase subscriptions. Each button is linked to a specific product and price in your Stripe account.
Create buy buttons in the Dashboard
Follow this guide to create buy buttons in the Dashboard. If you plan to use the entitlement checking functionality, ensure that the products you’ve created have Entitlements attached to them.
Display a buy button
Note
Buy buttons work even when users aren’t authenticated. The SDK creates a new Stripe Customer during purchase if needed.
Entitlements let you control access to premium features based on a customer’s active subscriptions.
Check a specific entitlement
Verify if a user has access to a specific feature:
Get all active entitlements
Retrieve all entitlements the customer has access to:
Listen for entitlement changes
Set up a listener to be notified when entitlements change:
Note
When no session is present, getActiveEntitlements() returns an empty array.
The customer portal lets subscribers manage their subscriptions, payment methods and billing information.
Show the customer portal
Present the portal when users need to manage their subscription:
Warning
The customer portal requires an active authenticated session. If the user isn’t logged in, the SDK throws an . error.
External redirection (optional)
You can also open the portal in a browser:
During development, use your sandbox API keys and sandbox Customer IDs to avoid creating real charges.
Testing scenarios
Test these common scenarios:
| Scenario | Steps |
|---|---|
| New subscription purchase | Present a buy button to a new user |
| Subscription management | Use the customer portal to change plans |
| Entitlement verification | Check a premium feature with hasEntitlement |
| Error handling | Test with invalid keys or expired sessions |
| Sign out flow | Verify billing. clears cached data |