# How Zuora Events Update Limio While Limio's Order Orchestration framework sends events to Zuora to keep subscription data in sync, Zuora can also send events back to Limio via webhooks. This enables bidirectional synchronisation, ensuring that changes made directly in Zuora (such as subscription renewals, cancellations, or attribute updates) are reflected in Limio. This document explains how Zuora events update Limio through the `handleZuoraEvent` API endpoint. {% content-ref url="/pages/UL5YnzYGgLehGMEed80m" %} [How Limio Events Update Zuora](/integrations/keeping-zuora-and-limio-in-sync/how-limio-events-updates-zuora-for-commerce.md) {% endcontent-ref %} ## API Endpoint | Property | Value | | ------------------ | -------------------------------------------- | | **Endpoint** | `POST /api/events/zuora` | | **Authentication** | IP whitelist only (Zuora workflow IP ranges) | | **CORS** | Enabled | ### Request Payload The endpoint accepts a JSON payload with the following schema: | Field | Type | Required | Description | | ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------- | | `subscriptionID` | string | Yes | The Zuora subscription ID or number used to identify the corresponding Limio subscription | | `type` | string | No | The event type (see supported types below) | | `data` | object | No | Additional event data to pass to the handler | **Example Request:** ```json { "subscriptionID": "A-S00012345", "type": "RenewSubscription", "data": { "renewalTerm": 12, "renewalTermPeriodType": "Month" } } ``` ## Supported Event Types The following event types are supported by the Zuora webhook handler: | Event Type | Description | Limio Actions | | -------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `CancelSubscription` | Cancellation initiated from Zuora |

Creates a related event in Limio

Updates subscription status to "cancelled"

Creates a subscription\_cancelled event for downstream processing

| | `RenewSubscription` | Subscription renewal processed in Zuora |

Creates a related event in Limio

Syncs subscription data including term dates, schedules, and billing information

| | `CreateSubscription` | New subscription created in Zuora | Syncs subscription data to Limio | | `TermsAndConditions` | Terms and conditions update | Syncs subscription data to Limio | | `AddProduct` | Product added to subscription | Syncs subscription data to Limio | | `UpdateProduct` | Product details updated | Syncs subscription data to Limio | | `RemoveProduct` | Product removed from subscription | Syncs subscription data to Limio | | `OwnerTransfer` | Subscription ownership transferred | Syncs subscription data to Limio | | `Suspend` | Subscription suspended | Syncs subscription data to Limio | | `Resume` | Subscription resumed | Syncs subscription data to Limio | ## What Gets Synced When a Zuora event triggers a subscription sync, the following data is updated in Limio: ### Subscription Data * **Status** - Updated to match Zuora subscription status (active, cancelled, etc.) * **Term dates** - `termStartDate` and `termEndDate` synchronised from Zuora * **Last synced timestamp** - Records when the sync occurred * **Quantity** - Updated if changed in Zuora (for non-FlatFee charge models) ### Customer & Address Data Unless `zuora.skip_sync_addresses` setting is enabled: * **Customer details** - First name, last name, account name, email, phone * **Billing address** - Synced from Zuora Bill To contact * **Delivery address** - Synced from Zuora Sold To contact ### Payment Methods Unless APM (Advanced Payment Manager) or Payment Profiles are enabled: * Default payment method synced from Zuora account * Payment method expiry dates updated if changed * New payment methods created in Limio if not already present ### Schedules * Existing schedules cancelled from the appropriate date * Past invoices recreated as historical schedules * Future schedules generated from Zuora order preview ### Products & Offers When product sync is enabled (not skipped): * New rate plans added as subscription offers in Limio * Expired or removed rate plans marked as ended in Limio * Offer attributes populated from Zuora product/rate plan data ### Salesforce Integration * CRM ID from Zuora account linked as Salesforce identity in Limio ## IP Whitelist The endpoint is secured using IP whitelisting. Only requests from Zuora's documented workflow IP ranges are accepted. The IP ranges are updated periodically based on [Zuora's published IP addresses](https://community.zuora.com/communities/community-home/digestviewer/viewthread?GroupId=475\&MessageKey=4813eaa3-a511-4224-a758-c5e13e9af0a7). ## Setting Up Zuora Notifications To configure Zuora to send events to Limio: 1. In Zuora, navigate to **Extension Studio > Events & Notifications** 2. Press **+ Add New Notification** 3. Select **On An Event Occurence** 4. Create a new event for the desired trigger event - i.e. for a Subscription Cancellation, this might look like: 1. ```
``` 5. Select **Delivered By Callout** and configure a new callout with: * **URL**: `https://your-limio-domain.com/api/events/zuora` * **Method**: POST * **Content-Type**: application/json * For **Authentication Type**, select OAuth. * If you don't already have a provider set up, create a new OAuth 2.0 Provider. For this, you will require a **Client ID** and Client Secret**.** These can be obtained by contacting our support helpdesk: . * Grant Type: **Client Credentials** * Access Token Endpoint: `https://your-limio-domain.com/oauth2/token` 6. Map the required fields in the payload: * `subscriptionID` - Use merge field for subscription number * `type` - Set to the appropriate event type * `data` - Include any additional context needed
How do I configure a renewal notification in Zuora? 1. Go to **Settings > Notifications** in Zuora 2. Click **Add New Notification** 3. Select **Subscription Renewed** as the trigger 4. In the callout configuration: * Set the URL to your Limio endpoint * Use the following payload template: ```json { "subscriptionID": "{SubscriptionNumber}", "type": "RenewSubscription", "data": { "renewalTerm": {RenewalTerm}, "termType": "{TermType}" } } ```
What happens if Zuora sends an event for a subscription that doesn't exist in Limio? The handler will attempt to look up the subscription by the provided `subscriptionID`. If no matching subscription is found in Limio, an error will be returned. Ensure that subscriptions are properly synced between Zuora and Limio before enabling webhook notifications.
Can I disable address syncing from Zuora? Yes. Set the general setting `zuora.skip_sync_addresses` to `true` in your Limio configuration. This prevents the webhook handler from overwriting subscription-level customer and address information with Zuora account contact data.
How does the sync handle payment profiles? If Payment Profiles are enabled (`processingOptions.enablePaymentProfiles`), the handler will skip payment method synchronisation. This is because payment methods are managed at the subscription level rather than the account level when using payment profiles. Similarly, if Advanced Payment Manager (APM) is enabled on the Zuora account (`APM__c = "True"`), payment method sync is skipped.
## Related Documentation * [How Limio Events Update Zuora](/integrations/keeping-zuora-and-limio-in-sync/how-limio-events-updates-zuora-for-commerce.md) * [Sync Between Limio Subscriptions and Zuora Subscriptions](/integrations/keeping-zuora-and-limio-in-sync/sync-between-limio-subscriptions-and-zuora-subscriptions.md) * [Order Orchestration Framework](/integrations/order-orchestration/order-orchestration-framework.md) If you have any questions, please contact us at . --- # 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/how-zuora-events-update-limio.md?ask= ``` 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.