> 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/sync-between-limio-subscriptions-and-stripe-subscriptions.md).

# Sync Between Limio and Stripe Subscriptions

For Limio-initiated actions such as a new order on the Limio Shop or a cancellation performed in Limio, Limio keeps Limio subscriptions in sync with Stripe subscriptions via its Order Orchestration framework.

However, for non-Limio-initiated actions, such as a Stripe-initiated cancellation due to payment failure, or a renewal processed directly in Stripe, the Limio Subscription might be out of sync with Stripe.

To prevent this, Limio provides a Subscription Sync for Stripe. **The Subscription Sync is primarily designed to handle Subscriptions that already exist in Limio.** For new subscriptions, we recommend using the Send Order API described below.

## Supported Stripe changes via Limio Sync

When a Limio Subscription Sync is triggered, it fetches the following from the Stripe Subscription and updates the corresponding values on the Limio Subscription:

* (1) update the subscription status (active / cancelled) and term start and end dates
* (2) update payment schedules: cancels future schedules and recreates them from paid and upcoming Stripe invoices
* (3) update payment method details: card brand, last four digits, and expiry date from the Stripe customer's default payment method

{% hint style="info" %}
Unlike the Zuora sync, the Stripe sync does not update addresses or customer name/email. Those fields are managed separately.
{% endhint %}

{% hint style="warning" %}
Currently, the Limio Sync cannot match a Limio Offer or Add-On to an externally-created Stripe Subscription. If you need Limio to include Catalog changes, please use the [Send Order API](#recommended-via-the-limio-send-order-api).
{% endhint %}

## How to trigger the Limio Subscription Sync

### Via the Subscription Sync API

The Limio Subscription Sync is available via the [Limio API](https://api.limio.com/#tag/Sync-Stripe-Data).

Make a POST request to the endpoint below, providing the **Limio subscription ID** (e.g. `sub-abc123`):

`/api/plugins/stripe/sync/subscription/{id}`

Example curl:

```
curl -i -X POST \
  'https://your-environment.prod.limio.com/api/plugins/stripe/sync/subscription/{limioSubscriptionId}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'
```

Example response:

```json
{
  "success": true,
  "id": "sub-5c3d83c60950014c306865f0ab8c499b"
}
```

{% hint style="danger" %}
Please ensure that **Limio-initiated orders are excluded from the process**. If Limio is the originator of a cancellation or renewal, synchronisation should not be triggered to prevent an infinite loop. Exclude orders where the source is identified as `shop` or `salesforce`.
{% endhint %}

## How to create Limio Subscriptions for new Subscriptions created directly in Stripe

### \[Recommended] Via the Limio Send Order API

If you are creating a Stripe Subscription outside of Limio Commerce, we recommend using Limio's Send Order API.

{% content-ref url="<https://docs.limio.com/api/orders-api>" %}
<https://docs.limio.com/api/orders-api>
{% endcontent-ref %}

Limio's Send Order API creates a new Subscription in Limio Commerce, Stripe, and other systems within Limio's [Order Orchestration framework](https://github.com/innovate42/innovate42-service-template/blob/docs/docs/_external/spaces/integrations/keeping-zuora-and-limio-in-sync/order-orchestration/order-orchestration-framework.md). This guarantees that all metadata is properly distributed and that Limio always has a relationship between its catalog concept and the connected systems.

### Via the Limio Sync Subscription API

{% hint style="warning" %}
Using the Limio Sync for Subscriptions that have not been initially created in Limio will result in limited functionality in Limio Self-Service. Currently, Limio does not allow commerce actions on subscriptions synced in this way. Please reach out to Limio at [**support@limio.com**](mailto:support@limio.com) if you plan on using this integration pattern.
{% endhint %}

If you need to create a subscription directly in Stripe and sync it into Limio, you can call the Subscription Sync API using the Limio subscription ID once the Limio subscription record has been created. For example:

`https://{TENANT}.prod.limio.com/api/plugins/stripe/sync/subscription/sub-5c3d83c60950014c306865f0ab8c499b`

Currently, Limio does not allow commerce actions, such as [cancellations](https://docs.limio.com/product/self-service/what-are-the-standard-functionality-of-limio-self-service-manage-my-account/how-to-create-a-personalised-cancelsave-experience), [switch](https://docs.limio.com/product/self-service/what-are-the-standard-functionality-of-limio-self-service-manage-my-account/how-to-create-a-personalised-switch-upgrade-or-downgrade-experience), or [renewals](https://docs.limio.com/product/self-service/what-are-the-standard-functionality-of-limio-self-service-manage-my-account/how-to-create-a-personalised-renewal-experience), on subscriptions synced in this way. Limited functionality is available, for example showing the [Invoice Table component](https://docs.limio.com/components/component-library/self-service-components/component-invoices-table) or the [Payment Table component](https://docs.limio.com/components/component-library/standard-components/component-payments-table).


---

# 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:

```
GET https://docs.limio.com/integrations/keeping-stripe-and-limio-in-sync/sync-between-limio-subscriptions-and-stripe-subscriptions.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.