How Limio Events Update Stripe

The Limio Order Orchestration framework processes customer actions by creating Events. Each Event triggers a Process Event with specific plugins that update external systems. Limio's Stripe plugin updates the Stripe data model via the Stripe API.

This document explains how Limio updates Stripe for each customer action. You can learn more about Limio's Order Orchestration framework at Order Orchestration Framework.

How each customer action in Limio updates Stripe

Commerce actions

These actions create or modify Stripe subscriptions and are revenue-impacting.

Customer journey	Description	Limio event	Stripe objects created / updated
New Order	A new purchase by a customer	Order Submitted	Stripe Customer (created, or matched to the logged-in customer's Limio identity: see How customers are matched) + Customer updated with billing details + Stripe Price (reused or created to match offer) + Stripe Subscription created + PaymentIntent attached to first Invoice
Cancel Subscription	Cancel an existing subscription	Order Cancel	Stripe Subscription updated to cancel at end of current billing period (end-of-term cancellation)
Change Address	Update address on the customer account	Order Change Address	Stripe Customer updated with address (billing), shipping (delivery), or both depending on address type configured. Identity fields (name, phone, email) are also updated.
Change Payment Method	Update the default payment method	Order Change Payment	Stripe Customer default payment method updated. Stripe Subscription updated to use the new PaymentMethod. A SetupIntent is used to securely collect the new payment details.
Upgrade	Switch to a higher-value offer	Order Switch	Stripe Subscription updated immediately with the new subscription item and price. The customer is credited for the prorated unused portion of the previous price and charged the full new price on the spot.
Downgrade	Switch to a lower-value offer	Order Switch	Stripe Subscription scheduled to switch at the end of the current billing period. No charge today — the new price applies at the next renewal.

Address update modes

When processing a Change Address, the Stripe plugin updates different fields depending on the configured address type:

Address type	Stripe fields updated
billing	customer.address
delivery	customer.shipping
all	Both customer.address and customer.shipping

How events work

Each event has its own payload, available via webhooks. Limio automatically calls the relevant Stripe API endpoints for the event type. The Stripe plugin creates or updates the Stripe Customer, Subscription, and Payment objects as documented in the Stripe API reference.

How customers are matched

Before creating a Stripe Customer, Limio looks for an existing one in two steps:

1. By Limio identity. If the order has an authenticated owner, Limio looks up the Stripe Customer already linked to that Limio customer record. If one exists, it is reused, preserving subscription history and payment methods.
2. By email and checkout ID. Otherwise, Limio lists Stripe Customers with the order's email and reuses one only if it also carries the same limio_basket_id (the checkout ID) in its metadata. This is a narrow safeguard against a page refresh mid-checkout creating a second Customer for the same basket.

If neither matches, a new Stripe Customer is created.

Email on its own does not deduplicate. An unauthenticated customer who returns in a new checkout and uses the same email address will get a new Stripe Customer, because the checkout ID differs. Deduplication across sessions relies on the customer being authenticated, so their orders resolve to the same Limio identity.

Plugin extensibility

The Stripe order plugin exposes hook points that allow tenant-specific plugins to modify behaviour:

Hook	Fires before	Purpose
beforeStripeSubscription	Subscription creation	Modify subscription parameters (e.g. trial periods, metadata, billing cycle anchors)
beforeStripePayInvoice	Invoice payment	Modify invoice payment parameters or handle custom billing scenarios

If you have any questions, please contact us at [e-mail].