Zuora Intro

Dev and Prod environments

Dev environment: apisandbox.zuora.com

Copy of prod: test.zuora.com

Prod: zuora.com

Subscriptions

The Product Catalog

The product catalog contains all the products The Guardian offers like Digital subscription, Guardian Weekly, Newspaper Vouchers, recurring contributions, etc. The products can be purchased either through the support website or by phoning into the call centre and having a CSR (customer service representative) place the order via Salesforce [link to salesforce UI maybe and what a CSR sees?].

Product rate plans

Each product contains one or more product rate plans. E.g.:

For the Guardian Weekly product, we have one rate plan for each billing frequency/period, i.e.: monthly, quarterly and annually. [add links here+ screenshots?]

For our Newspaper Delivery product, we have rate plans for each selection of days the paper can be delivered, i.e.: Sixday, Saturday, Sunday, Weekend, Everyday. [add links here+ screenshots?]

product rate plan charges

Each rate plan contains one or more product rate plan charges, which contains the price and currency.

I believe the reason there can be multiple charges is for de-duplication in the database and re-use of different charges in different plans, e.g.: for our Newspaper Delivery product, we have a charge for each day of the week. Then, each product rateplan will have the charge for the neccessary days assigned to it. [add links here+ screenshots?]

Subscription versions and amendments

to-do

Important fields from Zuora's API responses

imo Zuora has some bad descriptions for the following terms providing zero examples of usage: https://knowledgecenter.zuora.com/Billing/Billing_and_Payments/WA_Dates_in_Zuora/B_Subscription_and_Amendment_Dates

contractEffectiveDate is the day the subscription version is created in Zuora. E.g.: when purchasing a subscription on support.theguardian.com, the contractEffectiveDate will be the day of purchase. When performing a price-rise, the contractEffectiveDate will be the day the price-migration-engine creates the new subscription version in Zuora, even if it is not yet active. play.

Talk about Zuora's confusing 'active' state even though the rateplans may not be charged until the customerAcceptanceDate comes into

customerAcceptanceDate is the day the user begins paying for corresponding subscription version. E.g.: when a user starts their free trial of 14 days with a digital subscription (link to support repo code here), we set the customerAcceptanceDate 14 days in the future so they don't start paying for it yet.

Querying Zuora's SQL Database using ZOQL

Zuora runs on an SQL database, with their schema available here:

We can't query their database directly via SQL via some endpoint, but we can query it using Zuora's own SQL dialect named ZOQL. Unfortunately ZOQL is only limited to querying one table, no joins or fancy aggregation functions! :(

Relation to Salesforce

Syncing data between Zuora and Salesforce

One of the decisive reasons for choosing Zuora at the Guardian was Zuora 360/z360 (I think?). This is a product Zuora provides that automatically syncs all subscription data between Salesforce and Zuora in almost real-time, without us needing to write any code.

Useful API endpoints

subscriptions billing-preview payment-method

[add links here to code where we're using them + screenshots and JSON response bodies?]