# 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](https://github.com/innovate42/innovate42-service-template/blob/docs/docs/_external/spaces/order-orchestration/order-orchestration-framework.md).

## 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      | <p>Stripe Customer (created or matched by email)</p><p>+ Customer updated with billing details</p><p>+ Stripe Price (reused or created to match offer)</p><p>+ Stripe Subscription created</p><p>+ PaymentIntent attached to first Invoice</p> |
| 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 / Downgrade   | Switch to a different offer            | Order Switch         | Stripe Subscription updated with new subscription item and price matching the target offer. The previous subscription item is removed.                                                                                                         |

### 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](https://docs.stripe.com/api).

{% hint style="info" %}
When an existing Stripe Customer is found (matched by email), Limio reuses that customer record rather than creating a duplicate. This ensures subscription history and payment methods are preserved.
{% endhint %}

### 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 <support@limio.com>.