This project is not covered by Drupal’s security advisory policy.
A Stripe Billing payment gateway for Drupal Commerce. The customer pays on Stripe Checkout, Stripe runs the subscription, and the Commerce order follows what Stripe reports: an order is paid on invoice.paid and nothing else, and every later billing period gets an order of its own.
Sponsored and maintained by Vallic.
Use it when you want Stripe to own the subscription: billing dates, retries, dunning, proration, invoices, tax and the customer portal. Commerce keeps the order history. Commerce Recurring works the other way round: Drupal schedules the billing and charges a stored payment method. Pick one or the other for a given subscription.
Nothing sensitive reaches your site. Stripe holds the payment method and any mandate, and the order keeps the subscription's id.
Features
- Stripe Checkout in subscription mode, or payment mode for a one-off payment. Lines are priced inline from the order's adjusted unit prices, so there is no product catalogue to keep in sync in Stripe.
- Billing interval and trial days per order or from the gateway settings.
- Revisions: make the subscription bill what the order now says. Lines are matched one by one, with proration set to
create_prorations,always_invoiceornone. - Charges in arrears: add a one-off amount to the next invoice, safely retried with an idempotency key.
- Cancellation at a date or immediately, resuming a scheduled cancellation, or cancelling every subscription of a customer.
- Renewal orders: each later invoice becomes a placed and paid order, numbered with Stripe's invoice number and holding the lines Stripe charged.
- Safe event handling: every write to an order takes a lock and reloads the order. Payments are recorded once per Stripe invoice, however often Stripe resends the event.
- Customer portal: a portal configuration limited to payment methods and invoices, or your Stripe dashboard's default.
- Optional webhook submodule with signature verification. It dispatches an event for every verified Stripe event, so your own code can handle disputes, identity verification or anything else.
- Keys outside configuration: decorate one service to read the keys from
settings.phpor the environment. - Site conventions: metadata keys, lock names and which of your fields the module reads (owner, pending or closed lines, payment intent) are set in a container parameter.
- A
RecurringGatewayInterfacefor other modules, plus refunds, invoiced subscriptions (send_invoice), card fingerprints to refuse a second free trial, ending a trial early, test clocks and event replay.
Requirements
- Drupal 11
- Commerce 3 (Order, Payment, Price)
- stripe/stripe-php ^21.3, installed by Composer. The module pins the Stripe API version, so a library upgrade does not change what is sent to Stripe.
Getting started
composer require drupal/commerce_stripe_recurringand enable the module.- Add a payment gateway with the Stripe subscription plugin. Enter your secret and publishable keys. Test or live mode follows the key prefix.
- Enable Commerce Stripe Recurring Webhook and point a Stripe webhook endpoint at
/stripe/subscription/{gateway}/webhook. Enter its signing secret on the gateway. Subscribe to at leastcheckout.session.completed,invoice.paid,invoice.payment_failedandcustomer.subscription.deleted.
If you already receive Stripe events at an endpoint of your own, skip the submodule. Verify the signature there and pass the event to the commerce_stripe_recurring.order_events service. The README covers conventions, order data keys and running the tests.
Tested against Stripe
Kernel tests cover the gateway against an in-process Stripe fake. CI also runs them against stripe-mock, and an optional suite runs against Stripe test mode.
Need help using or extending this module?
- Hire the project maintainers: Vallic offers Drupal Commerce support and development, and runs Vallic Cloud, Drupal hosting.
- Community support: Use the issue queue.
Project information
- Project categories: E-commerce, Integrations
- Ecosystem: Commerce Core
- Created by valic on , updated
This project is not covered by the security advisory policy.
Use at your own risk! It may have publicly disclosed vulnerabilities.
