# Use Stripe Billing to enable subscriptions for Commercetools

Configure the Stripe app for Composable Commerce to enable subscriptions for any Commercetools product.

> This guide only applies to the Stripe app for Composable commerce and doesn’t cover the Checkout App integration.

You can enable [Subscriptions](https://docs.stripe.com/api/subscriptions.md) for any Commercetools product by defining the required attributes and variants in the product catalog section of the Commercetools merchant center. When a customer buys a subscription product, the integration uses Stripe Billing to register a recurring payment against that order. Stripe manages this subscription, attempting payment collection on a recurring basis based on the subscription settings in Commercetools. If a payment fails, Stripe can notify the customer and ask them to update their billing details. You can configure this in your [Subscriptions and emails settings](https://dashboard.stripe.com/settings/billing/automatic). If a payment succeeds, your website receives a [webhook](https://docs.stripe.com/webhooks.md) notification from Stripe. The module automatically creates a new order within Commercetools for each renewal increment. The app recalculates the shipping and tax amounts for each individual recurring subscription product before each iteration.

## Before you begin

- You have installed the Stripe Payment app for Composable Commerce.
- Stripe Billing is enabled in your Stripe account.
- You’ve created relevant products and their variants using the product type generated by the app called payment-app-subscription-information.
- Your [webhook endpoint handles](https://docs.stripe.com/webhooks.md#example-endpoint) the following events:
  - `invoice.paid`
  - `invoice.payment_failed`
![](https://b.stripecdn.com/docs-statics-srv/assets/stripe-composable-subscription-variants.25d631216cf8d4e5e31f75784f4a6cb6.png)

Product variant configuration

## How to enable and configure Subscriptions

[Subscriptions](https://docs.stripe.com/subscriptions.md) are enabled automatically when the recurring products are published on Commercetools storefront. The products are configured as one-time and recurring in Commercetools merchant center. To mark a product variant as a subscription, apply the **payment-app-subscription-information** custom type and define the following fields:

| Field                                 | Description                                                                                               |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `description`                         | A description for the subscription                                                                        |
| `recurring_interval`                  | Defines the billing frequency (`day`, `week`, `month`, `year`)                                            |
| `recurring_interval_count`            | Specifies the number of intervals between billings                                                        |
| `off_session`                         | Whether the subscription can be used off-session                                                          |
| `collection_method`                   | Payment collection method (`charge_automatically` or `send_invoice`)                                      |
| `days_until_due`                      | Optional number of days before the invoice is due (only applies when collection method is `send_invoice`) |
| `cancel_at_period_end`                | Optional flag to cancel at the end of the current period                                                  |
| `cancel_at`                           | Optional specific date and time to cancel the subscription                                                |
| `billing_cycle_anchor_day`            | Optional day of the month for billing                                                                     |
| `billing_cycle_anchor_time`           | Optional time of day for billing                                                                          |
| `billing_cycle_anchor_date`           | Optional specific date and time for billing anchor                                                        |
| `trial_period_days`                   | Optional trial period length in days                                                                      |
| `trial_end_date`                      | Optional specific date and time for trial end                                                             |
| `missing_payment_method_at_trial_end` | Optional behavior when payment method is missing at trial end (`cancel`, `create_invoice`, or `pause`)    |
| `proration_behavior`                  | Optional behavior for proration when making changes (`none`, `create_prorations`, or `always_invoice`)    |

## Core Components Overview

The Stripe subscription management is primarily managed by the following key services:

- **StripeSubscriptionService**: Main orchestrator for subscription operations
- **CtPaymentCreationService**: Handles CommerceTools payment creation
- **StripePaymentService**: Manages payment processing and order creation
- **SubscriptionEventConverter**: Converts Stripe events to CT transactions

## Handling Prorations
![](https://b.stripecdn.com/docs-statics-srv/assets/stripe-composable-subscriptions-proration.1155519547863ecf624f8aa9398f3a0e.png)

Handling Prorations

This app supports [prorations](https://docs.stripe.com/billing/subscriptions/prorations.md) automatically based on the product variant configuration in the Commercetools product catalog section. When enabled:

- For downgrades, a refund is automatically created and recorded as part of original order.
- For upgrades that require an extra payment, a new order creation is triggered with the prorated amount for the remainder of the billing period.

## Available services

This composable commerce app provides the core logic for subscription management, including support for mixed carts and order creation. The app exposes the essential API endpoints required to extend your subscription commerce use cases: creating and managing subscriptions, retrieving a customer’s subscription list, updating subscriptions with other commercetools products, and canceling subscriptions. You can extend the app by using packaged, prebuilt services:

| Endpoint service                                | Method | Description                                                                                   |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `/setupIntent`                                  | POST   | Can be used in trial mode, where a payment method can be captured for future payment recovery |
| `/subscription/withSetupIntent`                 | POST   | Create a subscription with trial setup on a commercetools product                             |
| `/subscription`                                 | POST   | Create a subscription (without trial)                                                         |
| `/subscription/confirm`                         | POST   | Confirm and finalize the subscription payment                                                 |
| `/subscription-api/:customerId`                 | GET    | Retrieve all subscriptions for a specific customer                                            |
| `/subscription-api/:customerId`                 | POST   | Update a customer’s subscription by upgrading or downgrading with a new commercetools product |
| `/subscription-api/:customerId/:subscriptionId` | DELETE | Cancel a specific subscription for a customer                                                 |