What the integration does

The ZOEY integration sends the services and charges you sell in The Layer to ZOEY, the billing platform from Tekton Billing. It works in the same way as the Abillity integration: customers become ZOEY accounts, sites become cost centres, and lines released from the Billing Exports app become ZOEY services and service charges.

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: when their details change, press Sync to ZOEY and ZOEY is brought into line. ZOEY's invoices come back to the ZOEY Billing tab on each customer. See ZOEY - Customer and Site sync and ZOEY - Billing tab, contacts and reconciliation.

Nothing is sent to ZOEY when a record is saved. Customers, sites and lines only go to ZOEY when someone presses a ZOEY button or releases lines from the Billing Exports app.

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.

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.

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. 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.
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 whether ZOEY is installed and ready. If it says something is missing, 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. This is the ZOEY tariff for the service that carries a product sold without a parent service. Use a tariff with no fixed charge of its own (a rate card only is fine): a tariff that bills anything itself 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.

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 this article for details.

Step 4: Map your products to ZOEY

Each product and service needs the ZOEY code it is billed with. These are set on the product in inventory.

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 a 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 recurring price, when the External SKU is a one-off charge.

Then 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.

The Sync to ZOEY button on a customer checks every line waiting to be released for that customer and shows any code ZOEY does not recognise, and the price ZOEY will bill for a service that has no monthly price in The Layer. See ZOEY - Customer and Site sync.

Step 5: 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.

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, 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.
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.

ZOEY - Setting up the ZOEY integration