# 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**](https://docs.limio.com/integrations/keeping-zuora-and-limio-in-sync/sync-between-limio-subscriptions-and-zuora-subscriptions) 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](https://docs.limio.com/product/authentication/sso-your-authentication/use-okta-with-limio-for-customers), [Auth0](https://docs.limio.com/product/authentication/sso-your-authentication/use-auth0-passwordless-with-limio)).

<figure><img src="/files/HNHm7tc4vsUXIAMTzTeP" alt=""><figcaption></figcaption></figure>

*Setting up a new Identity Provider*

3. Scroll to the **Identity Claims** section.
4. Add a claim with the **field name set to the Zuora Account ID claim**.
5. Configure as follows:
   * **Service**: `zuora`
   * **Issuer**: `zuora`
   * **Type**: `account`

<figure><img src="/files/0fJPR34qqeinsAqxTBiq" alt=""><figcaption></figcaption></figure>

*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.

<figure><img src="/files/7QCc25rJZ8FD0tkdYGQy" alt=""><figcaption></figcaption></figure>

*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](/integrations/keeping-zuora-and-limio-in-sync/sync-between-limio-catalog-and-zuora-catalog.md).

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

<figure><img src="/files/syj8XxdZPFoskylrJ69p" alt=""><figcaption></figcaption></figure>

*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](https://docs.limio.com/support).


---

# 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-zuora-and-limio-in-sync/configuring-zuora-to-limio-hot-sync.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.