Configure Zuora to Limio Hot Sync

🎉 Available from release 109 onwards

What is hot sync?

In scenarios where no external data migration has occurred to pre-populate Limio with subscription data from systems like Zuora, Limio offers a hot sync feature. This allows Limio to dynamically retrieve subscription data during customer login and populate Limio in real time.

The process is triggered based on identity claims in the user’s authentication token and ensures that customers can view and manage their subscriptions as though they originated in Limio.

⚠️ This feature is particularly useful for staged migrations or hybrid data strategies where some users are migrated, and others are not.

How does it work?

When a user logs in, Limio scans their ID token for a specific claim that identifies the user’s Zuora Account. If found, Limio initiates an asynchronous background sync with Zuora. This sync pulls in the user’s subscription data and updates Limio accordingly, similar to the existing Subscription Sync that can be triggered via API or via a Zuora callout.

The specific data synced is customer account data, subscription data (including subscription offers), payment methods (including the default payment method), the billing/shipping addresses from Zuora, and — from Release 114 — a Salesforce identity when the Zuora account has a CRM ID set, so that subsequent purchases re-use the existing Salesforce Account/Contact rather than creating duplicates.

This process can repeat at every login to ensure consistency between Zuora and Limio. Each sync event generates an event object in Limio, which can be monitored in the Events section for transparency and error tracking. This greatly simplifies keeping the systems in sync.

How to configure hot sync

Step 1: Configure identity claims in Limio

Limio supports two ways to identify the right Zuora Account during login. Choose the option that fits your IdP setup.

Option A: Token claim contains the Zuora Account ID directly

Use this when your IdP is already (or can easily be) configured to include the Zuora Account ID as a token claim.

1. Navigate to Settings > Authentication Providers.

2. Select the authentication provider you’ve configured (e.g. Okta, Auth0).

Setting up a new Identity Provider

1. Scroll to the Identity Claims section.

2. Add a claim with the field name set to the Zuora Account ID claim.

3. Configure as follows:

   • Service: zuora

   • Issuer: zuora

   • Type: account

Limio Identity setup with Claims

Limio also supports multiple Zuora Account ID claims. If multiple matching claims exist, each account will be queued individually for sync.

Option B: Token claim contains an external identifier, resolved via Zuora custom field

Use this when your IdP emits a standard user identifier (the OIDC sub claim, an email claim, or any unique value the IdP includes by default) and you don’t want to customise it. Most identity providers always include sub, so there’s typically nothing to add on the IdP side.

Limio looks up the right Zuora Account at login time by querying a custom field on the Zuora Account.

Prerequisites — set up by your team, on your Zuora:

1. Add a custom field to the Zuora Account object, for example LimioExternalId__c.

2. Populate that field with the user’s IdP subject ID for every Account that should be eligible for hot sync. Typically you wire this into your account-provisioning process so the field is set automatically when a Zuora Account is created.

Identity claim configuration in Limio:

1. Navigate to Settings > Authentication Providers.

2. Select your configured authentication provider.

3. In the Identity Claims section, add a claim and configure:

   • Claim (the token field whose value to look up): e.g. sub or email

   • Service: zuora

   • Issuer: zuora

   • Type: account

   • Account Lookup: turn on

   • Account Lookup Field: the Zuora Account custom field name (e.g. LimioExternalId__c)

When a user logs in, Limio will query Zuora for an Account where that custom field matches the claim value. The resolved Zuora Account drives the hot sync.

Behaviour notes:

• If no matching Zuora Account is found, login continues normally; hot sync is silently skipped for that user.

• The lookup is strict 1:1. If multiple Zuora Accounts share the same external ID value, no sync is triggered (and the case is logged for investigation).

✅ If these values are incorrect, Limio will not detect the claim and the hot sync will not be triggered.

Step 2: Enable hot sync in Limio Settings

1. Go to Settings > General Settings > Zuora > Zuora Sync Settings.

2. Enable the setting: Do you want to hot sync Zuora data into Limio when customers log in?

This is the main toggle that activates the hot sync functionality for all users.

Limio Settings for Hot Sync

🛑 It is currently not recommended to enable the sync options that automatically create Offers or Add-ons during hot sync. Learn more at Sync Between Limio and Zuora Catalogs.

Step 3: View hot sync events

When Limio detects new subscriptions during login, it creates a sync event, which appears in the Events log. These events:

• Are searchable and viewable in the Limio interface.

• Provide real-time feedback on sync success or failure.

• Can be treated similarly to orders for error handling and debugging

Example screenshot of an event is provided below.

Summary

By enabling and configuring hot sync:

• Customers can access and manage existing Zuora subscriptions in Limio.

• Subscriptions are automatically loaded based on ID token claims.

• Syncs are repeated at each login for data consistency.

This approach enables a seamless, real-time integration between Limio Self-Service and Zuora, even in hybrid or staged migration scenarios.

For further questions or advanced configuration guidance, please contact Limio Support.