> For the complete documentation index, see [llms.txt](https://docs.limio.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.limio.com/integrations/keeping-stripe-and-limio-in-sync/how-limio-events-update-stripe.md).

# 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](/integrations/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 to the logged-in customer's Limio identity: see <a href="#how-customers-are-matched">How customers are matched</a>)</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).

### 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&#x20;*****and*****&#x20;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.

{% hint style="warning" %}
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.
{% 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.