This page explains the different steps to configure a new Zuora tenant.
General information
Zuora has 2 datacenters :
EU and US
Hotel-Spider CH is hosted in the US Datacenter
Hotel-Spider DE is hosted in the EU Datacenter
We use the REST interface. Previously the code was based on SOAP but it is not available in the EU Datacenter !
The REST documentation can be found at https://www.zuora.com/developer/api-reference/
REST endpoints
| Tenant | base endpoint | Extranet |
|---|---|---|
| US Production | https://rest.zuora.com | https://www.zuora.com/ |
| US API Sandbox | https://rest.apisandbox.zuora.com | https://apisandbox.zuora.com |
| EU Production | https://rest.eu.zuora.com | https://eu.zuora.com |
| EU Sandbox | https://rest.sandbox.eu.zuora.com | https://sandbox.eu.zuora.com |
We authentify the system using the HTTP Headers apiAccessKeyId and apiSecretAccessKey.
Prequired
An access to the Zuora extranet with a user that has administrator role.
Note : If we want to use the same email on different tenants, we need to use an "alias". Example : firstname.lastname+de@hotel-spider.com
Every steps in this page supposes you are logged as an administrator in the corresponding Zuora extranet.
Make sure Zuora has activated all same modules as our Swiss account. Example : Owner Transfer Amendment
Data synchronisation
API User
User role
Go to Settings > Administation > Manage User Roles
Add new role :
IP Restriction
Add the staging and production IP
User API
Go to Settings > Administration > Manage Users
Click on Add single user.
For the user email, user an alias with a + :
example : dev+germany@hotel-spider.ch
For the work email, do not add the +alias
Store password and secret in Lastpass !
DO NOT ENABLE TWO-FACTOR AUTH!
To setup the password, you need to allow tempoarly your current IP for API USERS or you won't be able to set the passsword!
Security Policies
go to Settings > Administration > Setting Security Policies
Billing Settings
Default Subscription Settings
Default Term Type | Termed |
Default Initial Term (months) | 12 |
Default Renewal Term (months) | 12 |
Default Subscriptions to Auto-Renew? | Yes |
Require Customer Acceptance of Orders? | No |
Require Service Activation of Orders? | No |
Enable Subscriptions to be Invoiced Separately? | Yes |
Enable Automatic Price Change when Subscriptions are Renewed? | No |
Enable subscription auto-renew when there's no product in subscription? | No |
Subscription Auto Renew Job Type | System Default |
Customize Units Of Measure (UOM)
Go to Settings > Billing > Customize Unit of Measures
Carefull to not add any space or tabulation !
Active | Name | Displayed As | DecimalPlaces | Rounding Mode | Usage Log File Label | |
|---|---|---|---|---|---|---|
| Booking Channels | Booking Channels | 0 | Up | Booking Channels | |
| Rooms | Rooms | 0 | Up | Rooms | |
| Additional Booking Channels | Additional Booking Channels | 0 | Up | Additional Booking Channels | |
| Room Stay Amount | Room Stay Amount | 2 | Up | Room Stay Amount | |
| Reservation Amount | Reservation Amount | 2 | Up | Reservation Amount | |
| FAX A4 Page | FAX A4 Page | 0 | Up | FAX A4 Page | |
| Reservations | Reservation Count | 0 | Up | Reservation Count | |
| Callback | Callback | 0 | Up | Callback | |
| SMS | SMS | 0 | Up | SMS |
Customize Currencies
Go to Settings > Billing > Customize Currencies
Tourisoft Sàrl:
- CHF (default)
- EUR
Tourisoft GmbH:
- EUR (default)
Manage Custom Fields
Go to Settings > Billing > Manage Custom Fields
Note: when configuring the fields, DO NOT ADD the __c at the end, Zuora will do it after saving.
We use the following 2 types of data : Text and Picklist. Text fields have a maxlength indicated with a number in parentheses.
Custom fields can be Indexed or not
Account Fields (Indexed)
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| AccountType | AccountType__c | Picklist | YES | Hotel | Hotel, Affiliation, Whitelabel | Define account type synchronized from the V4 |
| Market | Market__c | Picklist | NO | - | Australia and New Zealand Benelux Caribbean Central America Central Asia DACH Eastern Africa Eastern Asia Eastern Europe France Melanesia Micronesia Middle Africa Northern Africa Northern America Northern Europe Polynesia South America South-Eastern Asia Southern Africa Southern Asia Southern Europe Western Africa Western Asia | Define which market the customer comes from |
| whitelabel_id | whitelabel_id__c | Text (4) | NO | - | ID of the whitelabel from where the customer comes. It is not required in case any account would need to be added in Zuora for any reason |
Product Fields (Indexed)
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| obj_id | obj_id__c | Picklist | YES | ID of the whitelabel for which the product is available. 0 means all whitelabels in the tenant will see this product For multiple whitelabels, the value can be separated by comas Example 1,6 for our Staging and Production | ||
| obj_id_class | obj_id_class__c | Picklist | YES | whitelabel | whitelabel affiliation hotel | Define the type of V4 object that can see this product |
Product Fields (Non-Indexed)
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| max_rates | max_rates__c | Picklist | YES | 15 | 15 100 1000 -1 | Max number of V4 rateplans the product allows to have -1 means it does not apply to this product |
| max_rooms | max_rooms__c | Picklist | YES | 15 | 15 100 1000 -1 | Max number of V4 rooms the product allows to have -1 means it does not apply to this product |
| max_products | max_products__c | Picklist | YES | 15 | 15 100 1000 -1 | Max number of v4 sellable products the product allows to have -1 means it does not apply to this product |
| SortOrder | SortOrder__c | Picklist | YES | 0 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | Sort order of the product, for display purpose |
Product Rate Plan Fields (Indexed)
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| obj_id | obj_id__c | Text (25) | NO | ID of the object for which this rateplan is available This fields is not used currently | ||
| obj_id_class | obj_id_class__c | Picklist | YES | hotel | hotel affiliation | Define the type of V4 object that can see this rateplan |
Product Rate Plan Fields (Non-Indexed)
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| bookingChannelId | bookingChannelId__c | text (5) | NO | Default booking channel ID applicable for Rate Plan. Used for CRS. | ||
| product_type | product_type__c | Text (25) | YES | First value | crs,pms administrative callback channelmanager spiderbooking pms wbe crs gateway sms fax discount duplicatechannel | Declare the type of rateplan. This is used for the limitations |
| SortOrder | SortOrder__c | Picklist | 0 | 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | Sort order of the product, for display purpose | |
| isviewable | isviewable__c | Picklist | YES | 1 | 0 1 | Define if a rateplan can be seen in the V4 |
| Mandatory | Mandatory__c | Picklist | YES | 0 | 0 1 | Define if the rateplan is mandatory for a product This is currently not used |
| Label | Label__c | Picklist | YES | First value | Administration V4 Communication Discount Commission Test | For display purpose, Declare what kind of rateplan this is |
| IncludedCountries | IncludedCountries__c | Text (255) | YES | {"Continent": "ALL"} | JSON that determine which countries can see this rateplan This is based on the list of Continent, SubContinent and Countries in the V4 database | |
| ExcludedCountries | ExcludedCountries__c | Text (255) | YES | {} | JSON that determine which countries can not see this rateplan This is based on the list of Continent, SubContinent and Countries in the V4 database |
Product Rate Plan Charges Fields (Non-Indexed)
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| isviewable | isviewable__c | Picklist | YES | 1 | 0 1 | Define if a rateplan can be seen in the V4 |
Subscription Rate Plan Fields (Non-Indexed)
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| bookingChannelId | bookingChannelId__c | Text (5) | This field is used for limitations and usage calculation. its purpose is to define which bookingChannelId from the v4 is attached to the rateplan. This value is then used to idenfy reservation source in the v4. |
Amendment Fields (Non-indexed
| Field Label | API Name | Data Type | Required | Default value | Possible values | Description |
|---|---|---|---|---|---|---|
| AmendmentVersionId | AmendmentVersionId__c | Text (15) | This field identifies an amendment from the v4 Usually it is the current version with "d" prefix | |||
| NumberOfAmendments | NumberOfAmendments__c | Text (5) | This field identifies how many amendment were sent together | |||
| DestinationInvoiceOwnerId | DestinationInvoiceOwnerId__c | Text (32) | Identify the destination invoice owner id. We can't read the destination owner id from Zuora query so we need to have a duplicate field for that | |||
| OldInvoiceOwnerId | OldInvoiceOwnerId__c | Text (32) | Identify the previous invoice owner id. We can't read the previous owner id from Zuora query so we need to have a duplicate field for that | |||
| AmendmentNumber | AmendmentNumber__c | Text (5) | This field identifies the amendment position in the group of amendment |
Define Billing Periods
Customize Billing Periods
Tourisoft Sàrl:
- Month (default)
- Quarter
- Semi-Annual
- Annual
all Tourisoft Sàrl products are to be defined prioritarily in monthly, as customers are required to pay monthly fees. The quarter, semi-annual, annual are active for specific products, for swiss clients until direct debit is made available. Some African customers also may optionally benefit from this as they have high banking fees and very slow and complicated banking transactions.
Tourisoft GmbH:
- Month (default)
Customize Billing Day
Default from Customer Account
Customize Billing Period Start Days
1st of the month
Customize List Price Base
Billing period
Billing Rules
Enable credit back for removing or canceling one time charges? | Yes |
Bill recurring charges for partial month (with monthly based billing periods)? | No |
Bill recurring charges for partial week (with weekly based billing periods)? | No |
Bill usage charges for partial month (with monthly based billing periods)? | No |
Bill usage charges for partial week (with weekly based billing periods)? | No |
When prorating a month, assume 30 days in a month or use actual days? | Use actual number of days |
When prorating periods greater than a month, prorate by month first, or by day? | Prorate by month first |
Support bill run auto-post? | Yes |
Default bill run to auto-post? | No |
Include invoices with negative totals in the Account Balance (included associated Debit Memos)? | Yes |
Include usage from child accounts when billing? | No |
How should errors be handled when generating multiple invoices for a single account via bill run? | Terminate processing of all invoices |
Preserve snapshot of bill-to and sold-to contacts when billing documents are posted? | No |
Invoice Past End-of-Term when Auto-Renew is OFF? | Yes: deprecated |
Invoice Past End-of-Term when Auto-Renew is ON? | Yes: deprecated |
Calculate taxes using information from Customer Account of: | Invoice owner |
Zuora Tax rounding rule for inclusive tax calculation | Round net amount |
When service period of an invoice item crosses multiple tax rate period, it will generate: | Multiple Tax Items |
Define Numbering and SKU Formats
| Account Number Prefix | A |
| SKU Prefix | SKU- |
| Subscription Number Prefix | A-S |
| Charge Number Prefix | C- |
| Amendment Number Prefix | A-AM |
Enable Charge Types / Models
Enable Charge Types
|
Enable Charge Models
|
Manage Billing Document Configuration
Manage Invoice Rules and Templates
Go to Settings > Billing > Manage Invoice Rules and Templates
The templates are setup in the following way:
- Per tenant (different template for Sàrl vs. GmbH)
- template for Hotels
- template for Whitelabels
- Per language:
- Sàrl:
- EN (default)
- DE
- ES
- FR
- NL
- GmbH:
- DE
- Sàrl:
To modify a template, click on the template name to download the existing word file (make sure to save a copy of the original and save the modified version under the latest version number, i.e. _v6). A folder with all templates exists under C:\Tourisoft\Accounting and Finance - General\Zuora. Make sure to save latest modifications there as backup.
Add the corresponding templates by clicking on "edit", select the template and save it. Use the preview function with existing customer data (to reflect reality) to make sure the latest modifications do not return errors.
The templates IDs will then need to be extracted from this page. Click on show ID:
Refer to the database section to store the template IDs in the v4.
Invoice prefix & Numbering
Go to Settings > Billing > Prefix & Numbering
Tourisoft Sàrl: INV
Tourisoft GmbH: RE
Customize Payment terms
Go to Settings > Billing > Customize Payment Terms
Add and activate the following payments : net10 and net30. (do not write Net30 !!!)
Setup Taxation Code
use the import file (CSV) TaxRates_Import_File.csv
One separate file for each tenant
Tourisoft Sàrl:
- Swiss VAT (7.7%) - as of 01.01.2018 - insert 0.077 in column G under Switzerland
Tourisoft GmbH:
- German VAT (19%) - insert 0.19 in column G under Germany
Batch
Bill runs
Charge types
Go to Settings > Billing > Enable Charge Types / Models
Check all charge models
Product Catalog
To be completed
Notification / Callouts configuration
Go to Settings > Billing > Setup Profiles, Notifications and Email Templates
First of all, disable ALL email callouts.
Invoices
Invoices net10 vs net30
The invoice due date is different based on the payment term :
| net10 | net30 | Meaning | Callout url net10 | callout url net30 | Name | Description |
|---|---|---|---|---|---|---|
| 20 days | 1 day | 30 days open | ?type=Invoice30DaysOverDue&paymentTerm=net10 | ?type=Invoice30DaysOverDue&paymentTerm=net30 | 1 Days Past Due | Invoice open for more than 30 days (netXYZ) |
| 43 days | 23 days | 53 days open | ?type=Invoice53DaysOverDue&paymentTerm=net10 | ?type=Invoice53DaysOverDue&paymentTerm=net30 | 23 days past due , pay or will block your account | Invoice open for more than 53 days (netXYZ) |
| 50 days | 30 days | 60 days open | ?type=Invoice60DaysOverDue&paymentTerm=net10 | ?type=Invoice60DaysOverDue&paymentTerm=net30 | 30 days past due, Account Blocked | Invoice open for more than 60 days (netXYZ) |
| 57 days | 37 days | 67 days open | ?type=Invoice67DaysOverDue&paymentTerm=net10 | ?type=Invoice67DaysOverDue&paymentTerm=net30 | 37 days past due, account blocked for 7 days | Invoice open for more than 67 days (netXYZ) |
| 64 days | 44 days | 74 days open | ?type=Invoice74DaysOverDue&paymentTerm=net10 | ?type=Invoice74DaysOverDue&paymentTerm=net30 | 44 days past due, account blocked for 14 days | Invoice open for more than 74 days (netXYZ) |
| 71 days | 51 days | 81 days open | ?type=Invoice81DaysOverDue&paymentTerm=net10 | ?type=Invoice81DaysOverDue&paymentTerm=net30 | 51 days past due, account blocked for 21 days | Invoice open for more than 81 days (netXYZ) |
| 78 days | 58 days | 88 days open | ?type=Invoice88DaysOverDue&paymentTerm=net10 | ?type=Invoice88DaysOverDue&paymentTerm=net30 | 58 days past due, account blocked for 28 days | Invoice open for more than 88 days (netXYZ) |
| 80 days | 60 days | 90 days open | ?type=Invoice90DaysOverDue&paymentTerm=net10 | ?type=Invoice90DaysOverDue&paymentTerm=net30 | 60 days past due, your case has been send to a collection agency | Invoice open for more than 90days (netXYZ) |
Invoices callout parameters
New Subscription
?type=NewSubscription
A new subscription has been created and activated.
Amendments
Cancellation
A subscription cancellation amendment has been submitted and processed.
?type=Cancellation
New product
An add new product amendment has been submitted and processed.
?type=NewProduct
Update Product
An update product amendment has been submitted and processed.
?type=UpdateProduct
Payments
Payment declined
First Attempt
?type=PaymentDeclined
The payment was declined by the payment gateway upon the first attempt.
Payment processed
The payment was processed successfully.
?type=PaymentProcessed
Payment expiration
30 Day Warning
?type=PaymentExpiration30Days
The credit card set as the default payment method on the account is within 30 days of expiration.
Database
Accounts are idenfitied by the field ZuoraTenantId of type INT in the tables
group.dbo.Hotels
v4.dbo.Affiliations
v4.dbo.whitelabels
Tenants are stored in the table [v4].[dbo].[ZuoraTenants]
- username and password are the credentials for the API user
- Password in database is encrypted
\Tools::encrypt('password');
- tenantId is the tenantId in the v4
- UOMMapping is used to map the UOMs. this is really helpfull for tenants that have anoying tabulations or spaces
{"duplicatechannels":"Duplicate Channels","bookingchannels":"Booking Channels","reservationamount":"Reservation Amount ","reservationcount":"Reservations"}
- Name is the name of the tenant
- InvoiceTemplates is the invoice template mapping in JSON format. example:
[{"name":"hotel_de","id":"8adc8f9968a1c7d60168a41c7e92567e","language":"de","type":"hotel"},{"name":"whitelabel_de","id":"8adc8f9968a1c7d60168a41c7e92567e","language":"de","type":"whitelabel"}]
- ZuoraCurrencyCodes : the currencies the tenant support. Separated by commas
- Endpoint is the base URL for the tenant
Tenant affecation for whitelabels are set in [v4].[dbo].[ZuoraWhitelabelTenant]. This table store the product catalog for a specific whitelabel on a tenant and also declare the default invoice template Id to use
Catalog importation
Open a SSH to a production machine and execute
php /var/www/cron/ZuoraProductCatalog.php
Tests
Add a new hotel by selecting the new tenant as destination and add a subscription to it.