How to specify the duration of subscription in Stripe - stripe-payments

Question

I am implementing stripe subscriptions and I can't find anywhere in the api documentation how to specify the duration of the subscription when creating a checkout session. This is what I have so far:
const customer = await stripe.customers.create({
description: "My First Test Customer (created for API docs)",
email: "some.email#gmail.com",
address: {
city: 'Toronto',
country: 'CA',
line1: "Some Address",
line2: "Some unit number",
postal_code: "M5G0V1",
state: "ON",
},
name: "Some Name",
phone: "Some Number",
});
const price = await stripe.prices.create({
unit_amount: 599,
currency: 'cad',
recurring: {interval: 'month', interval_count: '1'},
product: 'prod_KZfHFK4nfCqlGS',
});
const subscriptionSchedule = await stripe.subscriptionSchedules.create({
customer: customer.id,
start_date: 'now',
end_behavior: 'cancel',
phases: [
{
items: [
{
price: price.id,
quantity: 1,
},
],
iterations: 24,
},
],
});
console.log(subscriptionSchedule);
const session = await stripe.checkout.sessions.create({
success_url: 'http://localhost:8080/stripeSessionSuccessHook',
cancel_url: 'http://localhost:8080/stripeSessionCancelHook',
payment_method_types: ['card'],
customer: customer.id,
line_items: [
{price: price.id, quantity: 1},
],
mode: 'subscription',
});
I am trying to create a subscription that the customer pays monthly for 24 months. I am using Subscription Schedule suggested in the answers, and indeed such subscription with 24 months is being created. However, when creating a new checkout, and in case the payment is successful, it will create a Subscription that spans for 12 months... In the end, I have 2 subscriptions. One created by Subscription Schedule (24 months, desired one), and other Subscription (12 months). Is there a way I can somehow pass this subscription schedule to checkout, so 2 subscriptions don't get created.

Answer 1

A Subscription would typically auto-renew after every billing cycle if it is paid for. The recurring.interval is set in the Price and the max recurring interval is a year.
If you want to end the subscription after 2 years, you would use Subscription Schedules : https://stripe.com/docs/billing/subscriptions/subscription-schedules.
For your use case, with a Price that has recurring.interval=year, you would create a Subscription Schedule that has a single Phase with iterations=2 and end_behavior=cancel.
You can refer to this example : https://stripe.com/docs/billing/subscriptions/subscription-schedules/use-cases#installment-plans
Note that Subscription Schedules does not currently work with Checkout or the Customer Portal. If you want to use Checkout, a workaround is :
The customer pays for the subscription via Checkout
Create a Subscription Schedule for the existing (and already paid for) subscription : https://stripe.com/docs/billing/subscriptions/subscription-schedules/use-cases#existing-subscription
Update the newly created Subscription Schedule parameters to end the subscription after 2 years : https://stripe.com/docs/api/subscription_schedules/update
You should not depend on the success redirect to perform any important actions on the client. On the client, the customer could close the browser window or quit the app before the redirection occurs. You would want to setup a webhook to listen for the checkout.session.completed event and create the Subscription Schedule upon receipt of this event.
You can read more about setting up webhooks here :
https://stripe.com/docs/payments/checkout/fulfill-orders
https://stripe.com/docs/webhooks