# 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               | 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](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>.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.limio.com/integrations/keeping-stripe-and-limio-in-sync/how-limio-events-update-stripe.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.