ZOEY - Setting up the ZOEY integration
Why use the ZOEY integration
If you bill through ZOEY, the billing platform from Tekton Billing, every service and charge you sell has to be set up in ZOEY before it is billed, and every cease has to be disconnected there too. Done by hand from orders, emails or spreadsheets, lines get missed, prices are keyed wrongly and ceased services carry on billing.
The integration sends what was sold in The Layer to ZOEY, at the price it was sold for, for the right customer and site:
Nothing is keyed twice. Customers, sites, services and charges go to ZOEY from the records in The Layer, so ZOEY bills what was sold.
Finance stays in control. Nothing goes to ZOEY when a record is saved. Lines wait in the Billing Exports app until finance releases them, and each line is checked before it can go.
Nothing is billed twice. A service already connected is reused and a charge already sent is skipped, so a release can safely be run again.
Ceases are not forgotten. Each cease waits in the Change Queue until its service is disconnected in ZOEY, and overdue ones are shown in red.
You can check it agrees. The reconciliation compares every service The Layer bills with what ZOEY holds, and each customer's ZOEY invoices are on their record.
How it works
Each line goes through these stages:
Sell and convert. A sales order is converted to assets as usual. Lines whose billing route is ZOEY become Ready to Bill.
Check. The lines appear in the Billing Exports app on the ZOEY route, each checked for what ZOEY needs.
Release. Finance ticks lines and releases them. The customer's ZOEY account and the site's cost centre are created if they are not there yet, then services are connected and charges added. Released lines become In Billing.
Bill. ZOEY bills them. Its invoices appear on the customer's ZOEY Billing tab.
Cease. When an asset is ceased, the cease waits in the Change Queue until the service is disconnected in ZOEY.
Reconcile. The reconciliation lists any service where The Layer and ZOEY disagree.
In The Layer | In ZOEY |
Customer | Account |
Site | Cost centre (the default site is the account's primary cost centre) |
Billing contact | Contact on the site's cost centre |
Service asset and its number | Service on a tariff, with the number as its CLI |
Product asset, connection fee | Service charge (one-off or recurring) |
Cease date | Service disconnection |
The Layer is the record for customers and sites. Change their details in The Layer and press Sync to ZOEY, and ZOEY is brought into line. Changes made in ZOEY do not come back to The Layer.
Before you start
You will need:
The web address of your ZOEY system.
A ZOEY username and password that can use the ZOEY API. Tekton Billing can provide these.
Access to Settings in The Layer.
The ZOEY codes for what you sell: a tariff code for each service, and a charge code for each one-off or recurring charge. These are created in ZOEY, not in The Layer (see Step 4).
A ZOEY tariff to carry products sold without a service, with its fixed charge at 0.00 (see Step 3).
Set-up checklist
Add the ZOEY connector.
Install ZOEY.
Set up the ZOEY billing platform and test the connection.
Map your products to their ZOEY codes.
Check before the first release.
Give users their roles.
Release a first customer.
Step 1: Add the ZOEY connector
The Layer signs in to ZOEY through an Automation Builder connector, so the ZOEY password is kept in one place and is never shown to users.
Go to Settings - Automation Builder - Connectors and add a connector using the Zoey / Tekton Billing template.
Replace the demo address in Base URL and Login URL with your ZOEY address. Keep the endings: the Base URL ends in /api/v2 and the Login URL ends in /api/v2/auth.
Enter the ZOEY username and password, then save.
If the ZOEY password changes, update it on the connector. Nothing else needs to change. If you also use the Automation Builder ZOEY recipes, redeploy them after changing the password.
Step 2: Install ZOEY
Go to Settings - Scriptable Functions - Marketplace, find ZOEY (Tekton Billing) and click Install. Nothing is sent to ZOEY. This adds:
A ZOEY billing platform for your company, which you can choose as a billing route.
The ZOEY buttons on customers, sites and sales orders, and on the Billing Exports app.
The ZOEY upload files in the Billing Exports app and the Change Queue.
The ZOEY Billing tab on customers and the ZOEY Reconciliation in the Billing Exports app.
Installing again is safe. It fills in anything that is missing and keeps the choices you have made.
If finance integrations are enabled per sub-company, ZOEY must also be switched on for the sub-company of each customer you bill through it. See Enabling Finance Integrations per Sub-company.
Step 3: Set up the ZOEY billing platform
Go to Settings - Billing Platforms - ZOEY.
Setting | What it does |
Connector | The connector from Step 1. Accounts and cost centres linked through it are the ones billing uses. |
Cease cases | When ticked, ceasing a service on this billing route raises a cease case for the finance team. The cease case customisation must also be on. |
Connection | Test connection signs in to ZOEY through the saved connector and shows the result. Save the page first if you have just changed the connector. |
Reconciliation | Opens the ZOEY reconciliation for this billing route. Shown to users with the Billing Exports role. |
Function package | Shows Installed and ready once ZOEY is installed. If it says ZOEY is not installed, or is missing the address or tokens it calls back with, install ZOEY again. |
Account on release | Run during a release for a customer that has no ZOEY account yet, so the release can carry on. ZOEY: Sync Account is chosen when you install. Choose none to switch this off: those lines then fail and ask for the customer to be synced first. |
Cost centres on release | The same for a site that has no ZOEY cost centre yet. ZOEY: Sync Cost Centre is chosen when you install. |
Tariff for products | ZOEY charges always sit on a service, so a product sold without a parent service, such as a handset sold on its own, needs a service to carry its charges. This is the tariff of that service. Every ZOEY tariff has a fixed charge: create one in ZOEY with its fixed charge at 0.00 (a rate card is fine) and enter its code here. A tariff that bills more than 0.00 is refused, because ZOEY would add it to the product's charges. Leave it empty and those lines fail with a message instead. |
Disconnect replaced services | When ticked, releasing a New and Cease line also disconnects the service it replaces in ZOEY, at the end of its cease date. |
Save the page, then click Test connection before releasing anything. If the test fails, check the connector's address, username and password.
You can also make ZOEY the default platform for the Billing Exports app. See Setting a default billing platform for the Billing Exports app.
Step 4: Map your products to ZOEY
A release bills each line with the ZOEY codes held on its product. A missing or wrong code is the most common reason a line cannot be released, or is billed at the wrong price, so this step is worth doing carefully.
Create the codes in ZOEY first
Tariffs and charges are created in ZOEY, then their codes are added to the products in The Layer. The Layer never creates a tariff or charge in ZOEY, and never fills in a product's codes for you, so every product and service you bill through ZOEY needs its codes entered. Your ZOEY administrator can give you the list of tariff and charge codes.
Map by code, not by name. ZOEY can hold several tariffs with the same name, for example one for each network, and only the code says which one you mean.
Which code goes where
A service is billed on a ZOEY tariff, so its External SKU is a tariff code. A product, such as a handset, a licence or a support add-on, is billed as a charge on a service, so its External SKU is a charge code. Each ZOEY charge is either one-off or recurring.
Product field | For a service | For a product |
External SKU | The ZOEY tariff code. Required. | The ZOEY charge code, one-off or recurring. Required. |
Data Description | The one-off ZOEY charge code for its connection fee. Needed only if the service has an upfront price. | A one-off charge code for the upfront price, when the External SKU is a recurring charge. |
Pricing Tier | Not used. | A recurring charge code for the monthly price, when the External SKU is a one-off charge. |
Examples
What you sell | External SKU | Data Description | Pricing Tier |
A broadband service at £25.00 a month with a £50.00 connection fee | Its tariff code | A one-off charge code for the connection fee | Empty |
A handset sold for £129.00 | A one-off charge code | Empty | Empty |
A support add-on with a £25.00 set-up fee and £5.00 a month | A recurring charge code | A one-off charge code for the set-up fee | Empty |
A router included at no charge | A one-off charge code | Empty | Empty |
How the prices are billed
ZOEY bills the prices on the line as it was sold, which start as the product's prices. This is how each price is billed:
Price | How ZOEY bills it |
A service's monthly price | The tariff bills the service. If the tariff has one charge, The Layer's monthly price is set on the service as it is connected, in place of the tariff's. If the tariff has more than one charge, The Layer cannot set the price: match the product's price to the tariff, or set the price on the service in ZOEY after release. |
A service with no monthly price | ZOEY bills the tariff's own price. The line is marked Needs Attention so this is not missed. |
A service's upfront price | A one-off charge, using the code in Data Description. |
A product's upfront and monthly prices | A one-off charge for the upfront price and a recurring charge for the monthly price, at The Layer's prices, on the product's parent service. |
A product with no price at all | Sent once at 0.00 with its buy price, so the customer sees on the bill that it is included. Whether a 0.00 charge prints on the invoice is set on the charge in ZOEY. |
Any other price of zero | Not sent. For example, a product with an upfront price and no monthly price gets only its one-off charge. |
Set the billing routes
Set the upfront and recurring billing routes of these products and services to ZOEY. Only the prices whose billing route is ZOEY are sent to ZOEY, so a line can bill its upfront price on one platform and its recurring price on another. A product priced only on another billing route is not sent to ZOEY at all.
Mapping many products at once
Use the price book export and import (see How to Import Price Books into The Layer via spreadsheet (CSV)). In the file:
Product SKU (Supplier) is the External SKU.
Data Description and Pricing Tier hold the extra charge codes.
The import can also set the Up-front Cost Billing Route and Recurring Cost Billing Route.
Keep the column headings as exported, so each row updates the product it came from.
Step 5: Check before the first release
A check costs nothing, while a line that fails has to be fixed and released again. Before releasing a customer's lines:
Press Sync to ZOEY on the customer. Before anything is sent, its window lists the customer's lines waiting for ZOEY and looks up each tariff and charge code in ZOEY the way a release will. It shows codes ZOEY does not have, a charge of the wrong kind, a price with no charge code, and what ZOEY will bill for a service with no monthly price. To check without syncing, close the window instead of clicking Continue.
In the Billing Exports app, read the ZOEY Validation column on the Service Charges tab. It says why a line cannot be released and what needs a second look.
Step 6: User roles
App - Billing Exports gives access to the Billing Exports app, where lines are released to ZOEY, and to the ZOEY reconciliation.
Allow update billing shows the Change to In Billing and Change to Ignore Billing buttons. We recommend giving it to finance users only.
The role that allows changing the billing start date override decides who can delay a line's billing in Data Capture. See User Role Reference.
Users who cannot see the customer's Finance tab do not see the ZOEY Billing tab either.
Step 7: Release a first customer
Start with one customer, so you can check the result in ZOEY before releasing more.
Choose a customer with one or two lines on the ZOEY route.
Press Sync to ZOEY on the customer, read the checks and click Continue.
Open the Billing Exports app, choose ZOEY, tick the customer's lines and click Release to ZOEY.
When the batch has finished, check the Service Charges History tab, then open the account in ZOEY and check the services, prices and connect dates.
Once ZOEY has invoiced the customer, check their ZOEY Billing tab.
Payment method
Accounts and cost centres created by The Layer have payment method C (payment on account). ZOEY's own default can be Direct Debit, which the customer may not have authorised yet. Change it to Direct Debit in ZOEY once the customer's mandate is in place. The Layer never changes the payment method afterwards.
Using Automation Builder instead
Automation Builder has a ZOEY (Tekton Billing) group of recipes that use the same connector:
Validate a customer for ZOEY
Sync a customer to ZOEY
Sync a customer's sites to ZOEY cost centres
Disconnect a ceased service in ZOEY
They create the same accounts and cost centres as the installed buttons, also with payment method C, so you can use either. To have releases use a recipe, choose it in Account on release or Cost centres on release. Only the installed buttons bring existing accounts and cost centres into line with The Layer.
ZOEY limits worth knowing
Limit | What The Layer does |
500 API calls an hour | A release stops when about 20 calls are left and leaves the rest of the batch waiting. Use Re-sync batch once the hour has passed. Checks and the ZOEY Billing tab use the same allowance, so they read sparingly. |
Connect date within 90 days of today | A service whose billing start date is further away cannot be released, and the line says why. |
CLI must start with a letter or digit | Numbers are tidied first (spaces, brackets and dashes removed, +44 written as 0). A line with no number gets a placeholder CLI. |
Account and service names | Account names are cut to 100 characters, with commas and pipes sent as spaces. Service names keep letters, numbers, spaces and & - ( ) / only. |
One charge record per unit | A line with a quantity of 3 becomes three charges in ZOEY. |
Troubleshooting set-up
What you see | What to do |
Test connection fails | Check that the connector's Base URL ends in /api/v2 and its Login URL in /api/v2/auth, and that its username and password are right. Save the billing platform if you have just chosen the connector, then test again. |
ZOEY is not offered as a billing route | Install ZOEY (Step 2). Installing creates the ZOEY billing platform. |
Function package does not say Installed and ready, or a ZOEY button is missing | Install ZOEY again. It fills in anything missing and keeps your choices. |
Lines do not appear in the Billing Exports app | Choose ZOEY in the billing platform menu at the top-right of the app. Check that the product's billing route is ZOEY and that the order has been converted, so the line is Ready to Bill. |
A product sold on its own fails to release | Set the Tariff for products to a ZOEY tariff whose fixed charge is 0.00. |
A code is not found in ZOEY | Check the code on the product against ZOEY. If the tariff or charge does not exist yet, create it in ZOEY first. |