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.

How Limio Events Update Zuora

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:

{
  "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.

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: [email protected].

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

{
  "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

• Sync Between Limio Subscriptions and Zuora Subscriptions

• Order Orchestration Framework

If you have any questions, please contact us at [email protected].