Build a subscriptions integration

Create and manage subscriptions to accept recurring payments.

Checkout

Elements

Mobile

Learn how to sell fixed-price subscriptions. You’ll use the Mobile Payment Element to create a custom payment form that you embed in your app.

Note

If you’re selling digital products or services that are consumed within your app (for example, subscriptions, in-game currencies, game levels, access to premium content, or unlocking a full version), you must use Apple’s in-app purchase APIs. This rule has some exceptions, including one-to-one personal services and apps based in specific regions. See the App Store review guidelines for more information.

Build your subscription

This guide shows you how to:

• Model your business by building a product catalogue.
• Create a registration process to add customers.
• Create subscriptions and collect payment information.
• Test and monitor the status of payments and subscriptions.
• Let customers change their plan or cancel the subscription.
• Learn how to use flexible billing mode to access enhanced billing behaviour and additional features.

How to model it on Stripe

Subscriptions simplify your billing by automatically creating Invoices and PaymentIntents for you. To create and activate a subscription, you need to first create a Product to model what’s being sold and a Price which determines the interval and amount to charge. You also need either a customer-configured Account object or a Customer object to store PaymentMethods used to make each recurring payment.

API object definitions

Set up Stripe

The Stripe iOS SDK is open source, fully documented, and compatible with apps supporting iOS 13 or above.

To install the SDK, follow these steps:

1. In Xcode, select File > Add Package Dependencies… and enter https://github. the relevant part of the product as the repository URL.
2. Select the latest version number from our releases page .
3. Add the StripePaymentSheet product to the target of your app .

Note

For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.

Configure the SDK with your Stripe publishable key on app start. This enables your app to make requests to the Stripe API.

AppDelegate.swift

Select a language

Swift

Objective-C

No results

import UIKit
import StripePaymentSheet

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

 func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
 StripeAPI.defaultPublishableKey = "pk_test_GvF3BSyx8RSXMK5yAFhqEd3H"
 // do any other necessary launch configuration
 return true
 }
}

Note

Use your test keys while you test and develop, and your live mode keys when you publish your app.

And then install the Stripe CLI. The CLI provides webhook testing and you can run it to make API calls to Stripe. This guide shows how to use the CLI to set up a pricing model in a later section.

Install the Stripe CLI with npm:

Command Line

npm install -g @stripe/cli@latest

After installation, log in to your Stripe account:

Command Line

stripe login

After you install the CLI, you can also install agent tooling, or set up autocompletion.

Note

For more installation options for Windows, macOS, Linux and Docker, see the Stripe CLI readme on GitHub.

Create the pricing model Stripe CLI or Dashboard

Recurring pricing models represent the products or services you sell, how much they cost, what currency you accept for payments, and the service period for subscriptions. To build the pricing model, create products (what you sell) and prices (how much and how often to charge for your products).

This example uses flat-rate pricing with two different service-level options: Basic and Premium. For each service-level option, you need to create a product and a recurring price. To add a one-time charge for something like a setup fee, create a third product with a one-time price.

Each product bills at monthly intervals. The price for the Basic product is 5 USD. The price for the Premium product is 15 USD. See the flat rate pricing guide for an example with three tiers.

Go to the Add a product page and create two products. Add one price for each product, each with a monthly recurring billing period:

• Premium product: Premium service with extra features
• Price: Flat rate | 15 USD
• Basic product: Basic service with minimum features
• Price: Flat rate | 5 USD

After you create the prices, record the price IDs so you can use them in other steps. Price IDs look like this: price_G0FvDp6vZvdwRZ.

When you’re ready, use the Copy to live mode button at the top right of the page to clone your product from a sandbox to live mode.

Create the customer Client and Server

Stripe needs a customer for each subscription. In your application front end, collect any necessary information from your users and pass it to the backend.

If you need to collect address details, the Address Element enables you to collect a shipping or billing address for your customers. For more information on the Address Element, visit the Address Element page.

RegisterView.swift

struct RegisterView: View {
 @State var email = ""
 var body: some View {
 VStack {
 TextField(text: $email) {
 Text("Email")
 }
 Button {
 Task {
 var request = URLRequest(url: URL(string: "http://localhost:4242/create-customer")!)
 request.httpMethod = "POST"
 request.setValue("application/json", forHTTPHeaderField: "Content-Type")
 request.httpBody = try! JSONEncoder().encode(["email": email])
 let (data, _) = try! await URLSession.shared.data(for: request)
 let responseJSON = try! JSONSerialization.jsonObject(with: data) as! [String: Any]
 // Return the customer ID here
 print(responseJSON["customer"])
 }
 } label: {
 Text("Submit")
 }
 }
 }
}

On the server, create the Stripe customer object.

Use the Accounts v2 API to represent customers

The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a preview version in your code.

To join the Accounts v2 preview, go to Account previews and features in your Dashboard and enable Reusable payment methods for Global Payouts.

For most use cases, we recommend modelling your customers as customer-configured Account objects instead of using Customer objects.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Create the subscription Client and Server

Note

If you want to render the Payment Element without first creating a subscription, see Collect payment details before creating an Intent.

Let your new customer choose a plan and then create the subscription – in this guide, they choose between Basic and Premium.

In your app, pass the selected price ID and the ID of the customer record to the backend.

PricesView.swift

func createSubscription(priceId: String, customerAccountId: String) async -> SubscriptionsResponse {
 var request = URLRequest(url: URL(string: "http://localhost:4242/create-subscription")!)
 request.httpMethod = "POST"
 request.setValue("application/json", forHTTPHeaderField: "Content-Type")
 request.httpBody = try! JSONEncoder().encode(["customerAccountId": customerAccountId, "priceId": priceId])
 let (responseData, _) = try! await URLSession.shared.data(for: request)
 // SubscriptionsResponse is a Decodable struct conforming to the expected response from your backend.
 // It should include the client_secret, as discussed below.
 let subscriptionsResponse = try! JSONDecoder().decode(SubscriptionsResponse.self, from: responseData)
 return subscriptionsResponse
}

On the back end, create the subscription with status incomplete using payment_behavior=default_incomplete. Then return the client_secret from the subscription’s first payment intent to the front end to complete payment by expanding the confirmation_secret on the latest invoice of the subscription.

To enable improved subscription behaviour, set billing_mode[type] to flexible. You must use Stripe API version 2025-06-30.basil or later.

Set save_default_payment_method to on_subscription to save the payment method as the default for a subscription when a payment succeeds. Saving a default payment method increases the success rate of future subscription payments.

The following example creates a Subscription and expands the confirmation_secret from its latest invoice in the response. After the subscription is created, read subscription.latest_invoice.confirmation_secret.client_secret and return that value to the front end to confirm the payment.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Note

If you’re using a multi-currency Price, use the currency parameter to tell the Subscription which of the Price’s currencies to use. (If you omit the currency parameter, then the Subscription uses the Price’s default currency.)

The Subscription is now inactive and awaiting payment. The following example response highlights the minimum fields to store, but you can store whatever your application frequently accesses.

{
 "id": "sub_JgRjFjhKbtD2qz",
 "object": "subscription",
 "application_fee_percent": null,
 "automatic_tax": {
 "disabled_reason": null,
 "enabled": false,
 "liability": "null"
 },
 "billing_cycle_anchor": 1623873347,

Update your server endpoint

Add ephemeral key creation to the subscription endpoint and return it in the response:

Select a language

Ruby

Python

Node.js

PHP

Java

Go

.NET

No results

ephemeral_key = Stripe::EphemeralKey.create(
 {customer_account: customer_account_id},
 {stripe_version: '2026-03-25.dahlia'}
)

{
 subscriptionId: subscription.id,
 clientSecret: subscription.latest_invoice.confirmation_secret.client_secret,
 ephemeralKey: ephemeral_key.secret,
 customerAccountId: customer_account_id,
}.to_json

Update your response model

struct SubscriptionsResponse: Decodable {
 let subscriptionId: String
 let clientSecret: String
 let ephemeralKey: String
 let customerAccountId: String
}

Pass the customer configuration to PaymentSheet

Add the following when configuring PaymentSheet:

config.customerAccount = .init(id: customerAccountId, ephemeralKeySecret: ephemeralKey)

Collect payment information Client

Use the Payment Sheet to collect payment details and activate the subscription. You can customise Elements to match the look and feel of your application.

The Payment Sheet securely collects all necessary payment details for a wide variety of payments methods. Learn about the supported payment methods for Payment Sheet and Subscriptions.

Add the Payment Element to your app

Note

This step shows one way to get started, but you can use any in-app payments integration.

Initialise and present the Mobile Payment Element using the PaymentSheet class.

SubscribeView.swift

struct SubscribeView: View {
 let paymentSheet: PaymentSheet
 @State var isPaymentSheetPresented = false
 init(clientSecret: String) {
 var config = PaymentSheet.Configuration()
 // Set `allowsDelayedPaymentMethods` to true if your business handles
 // delayed notification payment methods like US bank accounts.
 config.allowsDelayedPaymentMethods = true
 config.primaryButtonLabel = "Subscribe for $15/month"
 self.paymentSheet = PaymentSheet(paymentIntentClientSecret: clientSecret, configuration: config)
 }
 var body: some View {
 Button {
 isPaymentSheetPresented = true
 } label: {
 Text("Subscribe")
 }.paymentSheet(isPresented: $isPaymentSheetPresented, paymentSheet: paymentSheet) { result in
 switch result {
 case .completed:
 // Handle completion
 case .canceled:
 break
 case .failed(let error):
 // Handle error
 }
 }
 }
}

The Mobile Payment Element renders a sheet that allows your customer to select a payment method. The form automatically collects all necessary payments details for the payment method that they select.

Setting allowsDelayedPaymentMethods to true allows delayed notification payment methods like US bank accounts. For these payment methods, the final payment status isn’t known when the PaymentSheet completes, and instead succeeds or fails later. If you support these types of payment methods, inform the customer their order is confirmed and only fulfil their order (for example, ship their product) when the payment is successful.

You can customise the Payment Element to match the design of your app by using the appearance property your PaymentSheet.Configuration object.

Confirm payment

The Mobile Payment Element creates a PaymentMethod and confirms the incomplete Subscription’s first PaymentIntent, causing a charge to be made. If Strong Customer Authentication (SCA) is required for the payment, the Payment Element handles the authentication process before confirming the PaymentIntent.

Set up a return URL Client-side

The customer might navigate away from your app to authenticate (for example, in Safari or their banking app). To allow them to automatically return to your app after authenticating, configure a custom URL scheme and set up your app delegate to forward the URL to the SDK. Stripe doesn’t support universal links.

SceneDelegate.swift

Swift

// This method handles opening custom URL schemes (for example, "your-app://stripe-redirect")
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
 guard let url = URLContexts.first?.url else {
 return
 }
 let stripeHandled = StripeAPI.handleURLCallback(with: url)
 if (!stripeHandled) {
 // This was not a Stripe url – handle the URL normally as you would
 }
}

Additionally, set the returnURL on your PaymentSheet.Configuration object to the URL for your app.

var configuration = PaymentSheet.Configuration()
configuration.returnURL = "your-app://stripe-redirect"

Optional Enable Apple Pay

Listen for webhooks Server

To complete the integration, you need to process webhooks sent by Stripe. These are events triggered whenever state inside of Stripe changes, such as subscriptions creating new invoices. In your application, set up an HTTP handler to accept a POST request containing the webhook event, and verify the signature of the event:

server.rb

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

During development, use the Stripe CLI to observe webhooks and forward them to your application. Run the following in a new terminal while your development app is running:

Command Line

stripe listen --forward-to localhost:4242/webhook

For production, set up a webhook endpoint URL in the Dashboard, or use the Webhook Endpoints API.

You need to listen to a few events to complete the remaining steps in this guide. See Subscription events for more details about subscription-specific webhooks.

Provision access to your service Client and Server

Now that the subscription is active, give your user access to your service. To do this, listen to the customer.subscription.created, customer.subscription.updated, and customer.subscription.deleted events. These events pass a subscription object which contains a status field indicating whether the subscription is active, past due or cancelled. See the subscription lifecycle for a complete list of statuses.

In your webhook handler:

1. Verify the subscription status. If it’s active then your user has paid for your product.
2. Check the product the customer subscribed to and grant access to your service. Checking the product instead of the price gives you more flexibility if you need to change the pricing or billing interval.
3. Store the product. id , subscription. id and subscription. status in your database along with the customer. id you already saved. Check this record when determining which features to enable for the user in your application.

The state of a subscription might change at any point during its lifetime, even if your application doesn’t directly make any calls to Stripe. For example, a renewal might fail due to an expired credit card, which puts the subscription into a overdue state. Or, if you implement the customer portal, a user might cancel their subscription without directly visiting your application. Implementing your handler correctly keeps your application state in sync with Stripe.

Cancel the subscription Client and Server

It’s common to allow customers to cancel their subscriptions. This example adds a cancellation option to the account settings page.

The example collects the subscription ID on the front end, but your application can get this information from your database for your logged-in user.

Account settings with the ability to cancel the subscription

SubscriptionView.swift

func cancelSubscription() async {
 var request = URLRequest(url: URL(string: "http://localhost:4242/cancel-subscription")!)
 request.httpMethod = "POST"
 request.setValue("application/json", forHTTPHeaderField: "Content-Type")
 request.httpBody = try! JSONEncoder().encode(["subscriptionId": subscription.id])
 let (subscriptionResponse, _) = try! await URLSession.shared.data(for: request)
 // Update the state to show the subscription has been cancelled
}

On the back end, define the endpoint for your app to call.

server.rb

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc')

post '/cancel-subscription' do
 content_type 'application/json'
 data = JSON.parse request.body.read

 deleted_subscription = client.v1.subscriptions.cancel(data['subscriptionId'])

 deleted_subscription.to_json
end

Your back end receives a customer.subscription.deleted event.

After the subscription is cancelled, update your database to remove the Stripe subscription ID you previously stored, and limit access to your service.

When a subscription is cancelled, it can’t be reactivated. Instead, collect updated billing information from your customer, update their default payment method, and create a new subscription with their existing customer record.

Test your integration

Test payment methods

Use the following table to test different payment methods and scenarios.

Monitor events

Set up webhooks to listen to subscription change events, such as upgrades and cancellations. Learn more about subscription webhooks. You can view events in the Dashboard or with the Stripe CLI.

For more details, see testing your Billing integration.

Optional Let customers change their plans Client and Server

Optional Preview a price change Client and Server

Optional Display the customer payment method Client and Server

Disclose Stripe to your customers

Stripe collects information on customer interactions with Elements to provide services to you, prevent fraud, and improve its services. This includes using cookies and IP addresses to identify which Elements a customer saw during a single checkout session. You’re responsible for disclosing and obtaining all rights and consents necessary for Stripe to use data in these ways. For more information, visit our privacy center.