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

Unlike the Zuora sync, the Stripe sync does not update addresses or customer name/email. Those fields are managed separately.

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.

How to trigger the Limio Subscription Sync

Via the Subscription Sync API

The Limio Subscription Sync is available via the Limio API.

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:

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

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.

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.

https://docs.limio.com/api/orders-api

Limio's Send Order API creates a new Subscription in Limio Commerce, Stripe, and other systems within Limio's Order Orchestration framework. 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

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 [email protected] if you plan on using this integration pattern.

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, switch, or renewals, on subscriptions synced in this way. Limited functionality is available, for example showing the Invoice Table component or the Payment Table component.