Zephr User Guide

Zuora Listener

4 views 0

Zuora offers powerful subscription management and payment gateway services. The Zephr Zuora integration currently provides a way to synchronize subscription statuses for users from Zuora to Zephr.

Behaviour

The extension will register an HTTP listener to receive incoming Callout Notifications from Zuora.

Upon receiving a notification, Zephr will call back to Zuora to verify information received and make any necessary changes to end-user product access.

The extension is designed to be compatible with customers using Zephr’s JWT recognition. As such, there may be cases where a notification is received for a change to a subscription relating to a user who does not have a record in the Zephr user store. In this case, the extension conducts extra verification with Zuora, creates that user and then synchronizes product grants in the usual way.

An active subscription in Zuora is represented by a product grant in Zephr with start and end dates that correspond to the ratePlanCharge object attached to the subscription object (subscription.ratePlans.<ratePlan>.ratePlanCharges.<ratePlanCharge>.{effectiveStartDate|effectiveEndDate}).

This data does not need to be included in the Callout Notification sent to Zephr: on receipt of a notification, Zephr will look up the necessary information in Zuora.

In addition to this, the extension also has handling for grace periods defined against products in Zuora. This means that when a subscription in Zuora changes to the suspended status, Zephr will remove any existing product grants, and re-add a grant but with an expiry date including the grace period.

Configuration

To enable the Zuora Listener Extension within Zephr, navigate to Settings > Extensions > Zuora. If you cannot see the Zuora option in your list of Extensions, email support@zephr.com.

Once on the configuration screen for the extension, you will need to enter the following details:

  • Zuora API (API credentials and base URL)
  • Product Mapping (a flat JSON object mapping Zuora Product SKUs to Zephr Product IDs)
  • Key Lookups:
    • Foreign System Key: the ID of the key used to identify the 3rd-party identity system in Zephr (e.g. gigya)
    • Zuora to Zephr Foreign Key: the property in Zuora used to denote the 3rd-party ID (e.g. Gigya_Id_Utilizer__c). NOTE: it is expected that this property will exist on the Subscription object in Zuora.
    • Zuora Product Grace Period Key: the property in Zuora used to denote any grace period for a given product (e.g. Grace_Period__c). NOTE: it is expected that this property will be on the Product object in Zuora.

Activate Plugin

Once you’ve input the relevant details, you will need to confirm which of your Sites the extension should be active on. To do this, use the toggles for each site under the Activate Plugin section, or choose Select All Sites.

Mailchimp - Plugin Activation

Once completed, click Save. Your Extension is now Enabled.

Usage

When active for a given site, the extension will register a listener at the following endpoint: /plugins/public/zuora/webhook. 29This endpoint expects notifications to be POSTed with a JSON payload matching the following schema:

{
    "AccountID": "<uuid>",
    "GigyaID": "<uuid>",
    "Email": "<email>",
    "ContactID": "<uuid>" // OPTIONAL
}

An example of a full notification body would be:

{
    "AccountID": "05953d7e-75e3-445d-94b4-cc22018e5594",
    "GigyaID": "912d4f17-9be0-4ff6-8b71-cd30a0cb04a1",
    "Email": "email@company.com",
    "ContactID": "1d073f7b-b4a6-4134-bbf4-47eec7a9dc19"
}

NOTE: ContactID is not used at present.