Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 22 Next »

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

Tenantbase endpointExtranet
US Productionhttps://rest.zuora.comhttps://www.zuora.com/
US API Sandboxhttps://rest.apisandbox.zuora.comhttps://apisandbox.zuora.com
EU Productionhttps://rest.eu.zuora.comhttps://eu.zuora.com
EU Sandboxhttps://rest.sandbox.eu.zuora.comhttps://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

Go to Settings > Billing > Default Subscription Settings
Set the defaults to use when creating a new subscription.
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

YES

Booking Channels

Booking Channels

0

Up

Booking Channels

YES

Rooms

Rooms

0

Up

Rooms

YES

Additional Booking Channels

Additional Booking Channels

0

Up

Additional Booking Channels

YES

Room Stay Amount

Room Stay Amount

2

Up

Room Stay Amount

YES

Reservation Amount

Reservation Amount

2

Up

Reservation Amount

YES

FAX A4 Page

FAX A4 Page

0

Up

FAX A4 Page

YES

Reservations

Reservation Count

0

Up

Reservation Count

YES

Callback

Callback

0

Up

Callback

YES

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 LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
AccountTypeAccountType__cPicklistYESHotelHotel, Affiliation, WhitelabelDefine account type synchronized from the V4
MarketMarket__cPicklistNO-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_idwhitelabel_id__cText (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 LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
obj_idobj_id__cPicklistYES

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_classobj_id_class__cPicklistYESwhitelabelwhitelabel
affiliation
hotel		Define the type of V4 object that can see this product

Product Fields (Non-Indexed)

Field LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
max_ratesmax_rates__cPicklistYES1515
100
1000
-1

Max number of V4 rateplans the product allows to have

-1 means it does not apply to this product

max_roomsmax_rooms__cPicklistYES1515
100
1000
-1

Max number of V4 rooms the product allows to have

-1 means it does not apply to this product 

max_productsmax_products__cPicklistYES1515
100
1000
-1

Max number of v4 sellable products the product allows to have

-1 means it does not apply to this product

SortOrderSortOrder__cPicklistYES00
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 LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
obj_idobj_id__cText (25)NO

ID of the object for which this rateplan is available

This fields is not used currently

obj_id_classobj_id_class__cPicklistYEShotelhotel
affiliation		Define the type of V4 object that can see this rateplan

Product Rate Plan Fields (Non-Indexed)

Field LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
product_typeproduct_type__cText (25)YESFirst valuecrs,pms
administrative
callback
channelmanager
spiderbooking
pms
wbe
crs
gateway
sms
fax
discount
duplicatechannel

Declare the type of rateplan. This is used for the limitations

SortOrderSortOrder__cPicklist
00
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
isviewableisviewable__cPicklistYES10
1		Define if a rateplan can be seen in the V4
MandatoryMandatory__cPicklistYES00
1

Define if the rateplan is mandatory for a product

This is currently not used

LabelLabel__cPicklistYESFirst valueAdministration
V4
Communication
Discount
Commission
Test

For display purpose,

Declare what kind of rateplan this is

IncludedCountriesIncludedCountries__cText (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

ExcludedCountriesExcludedCountries__cText (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 LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
isviewableisviewable__cPicklistYES10
1		Define if a rateplan can be seen in the V4

Subscription Rate Plan Fields (Non-Indexed)

Field LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
bookingChannelIdbookingChannelId__cText (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 LabelAPI NameData TypeRequiredDefault valuePossible valuesDescription
AmendmentVersionIdAmendmentVersionId__cText (15)


This field identifies an amendment from the v4

Usually it is the current version with "d" prefix

NumberOfAmendmentsNumberOfAmendments__cText (5)


This field identifies how many amendment were sent together 
DestinationInvoiceOwnerIdDestinationInvoiceOwnerId__cText (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

OldInvoiceOwnerIdOldInvoiceOwnerId__cText (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

AmendmentNumberAmendmentNumber__cText (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

Set your company's Billing Policies.
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)?
Yes
Bill usage charges for partial month (with monthly based billing periods)?
No
Bill usage charges for partial week (with weekly based billing periods)?
Yes
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:
One Tax Item

Define Numbering and SKU Formats

Account Number PrefixA
SKU PrefixSKU-
Subscription Number PrefixA-S
Charge Number PrefixC-
Amendment Number PrefixA-AM

Enable Charge Types / Models

Enable Charge Types

Use the checkbox below to indicate if your organization uses usage-based charges in its pricing
Select
Name
YES
Usage-Based Pricing

Enable Charge Models

Use the checkboxes below to indicate the charge models that your organization uses in its pricing
Select
Name
YES
Flat Fee Pricing
YES
Per Unit Pricing
YES
Overage Pricing
YES
Volume Pricing
YES
Tiered Pricing
YES
Tiered with Overage Pricing
YES
Discount-Fixed Amount
YES
Discount-Percentage

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:

  1. Per tenant (different template for Sàrl vs. GmbH)
  2. template for Hotels
  3. template for Whitelabels
  4. Per language:
    1. Sàrl:
      1. EN (default)
      2. DE
      3. ES
      4. FR
      5. NL
    2. GmbH:
      1. DE

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 :

net10net30MeaningCallout url net10callout url net30NameDescription
20 days1 day30 days open?type=Invoice30DaysOverDue&paymentTerm=net10?type=Invoice30DaysOverDue&paymentTerm=net301 Days Past Due Invoice open for more than 30 days (netXYZ)
43 days23 days53 days open?type=Invoice53DaysOverDue&paymentTerm=net10?type=Invoice53DaysOverDue&paymentTerm=net3023 days past due , pay or will block your account Invoice open for more than 53 days (netXYZ)
50 days30 days60 days open?type=Invoice60DaysOverDue&paymentTerm=net10?type=Invoice60DaysOverDue&paymentTerm=net3030 days past due, Account Blocked Invoice open for more than 60 days (netXYZ)
57 days37 days67 days open?type=Invoice67DaysOverDue&paymentTerm=net10?type=Invoice67DaysOverDue&paymentTerm=net3037 days past due, account blocked for 7 days Invoice open for more than 67 days (netXYZ)
64 days44 days74 days open?type=Invoice74DaysOverDue&paymentTerm=net10?type=Invoice74DaysOverDue&paymentTerm=net3044 days past due, account blocked for 14 days Invoice open for more than 74 days (netXYZ)
71 days51 days81 days open?type=Invoice81DaysOverDue&paymentTerm=net10?type=Invoice81DaysOverDue&paymentTerm=net3051 days past due, account blocked for 21 days Invoice open for more than 81 days (netXYZ)
78 days58 days88 days open?type=Invoice88DaysOverDue&paymentTerm=net10?type=Invoice88DaysOverDue&paymentTerm=net3058 days past due, account blocked for 28 days Invoice open for more than 88 days (netXYZ)
80 days60 days90 days open?type=Invoice90DaysOverDue&paymentTerm=net10?type=Invoice90DaysOverDue&paymentTerm=net3060 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.


  • No labels