Use Stripe Billing to enable subscriptions for Commercetools

You can enable Subscriptions 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. If a payment succeeds, your website receives a webhook 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 have created relevant products and their variants using the product type generated by the app called payment-app-subscription-information.
• Your webhook endpoint handles the following events:
  • invoice.paid
  • invoice.payment_failed

Product variant configuration

How to enable and configure Subscriptions

Subscriptions 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:

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

Handling Prorations

This app supports prorations 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: