Try a test account with sample data
Open your utility's test account, browse sample customers, readings and invoices, and test simulated payments without touching live records.
Updated on
The sandbox is a test account attached to your utility's account and pre-filled with sample data, so you can try customers, readings, billing and payments before using real data. The person who registers the utility becomes the sandbox Owner.
Before you start#
- Your plan must include Sandbox workspaces. Without that capability, the account is created with no sandbox.
- Colleagues you invite later do not join the sandbox on their own: only the person who created the account has access at first.
Step 1: Create the account and enter the sandbox#
- On the site's Sandbox page, click "Create account & open sandbox".
- On the Register your company screen, check that the Open directly in Sandbox notice is shown.
- Fill in Company name, Your full name, Email or phone and Password, then click Create account.
- The dashboard opens inside the sandbox. A band at the top reminds you that you are in a sandbox and the data is test data.
Step 2: Browse the sample data#
- Open Customers. Six sample holders are listed, each with a property, an account, an installed meter and an active connection.
- Open Readings, then All readings, to see one month's reading cycle, captured on the sample routes.
- Open Billing, then Invoices. The sample billing run has already finished: some invoices are paid and the rest are open, ready for collection tests.
- Open Tariffs to see the prices that calculated those invoices.
Step 3: Switch between the sandbox and the live account#
- Open the Your account menu at the top of the sidebar.
- To go back to the live account, choose Exit sandbox.
- To return, choose Switch to sandbox and pick the sandbox. Its name is your utility's name followed by "Sandbox".
Step 4: Simulate payments and new readings#
- In the sandbox, online payments go through a simulated connector that picks the outcome from the cents of the amount: 02 fails, 05 expires, 09 stays pending, and 00 or any other ending confirms. To create a payment from the command line, run
gotactl events trigger invoice.paid. It issues a sample invoice and pays it through the simulated connector. - To finish pending payments, run
gotactl sandbox advance. The--outcomeflag takesconfirmed,failedorexpired, and--paymentlimits the run to one payment. - To also generate a new reading cycle, add
--readings:gotactl sandbox advance --readings. Every meter gets one new reading, 12.5 m³ above its last one.
What happens next#
A confirmed payment fires the same confirmation webhooks it would fire in the live account, and the invoice becomes paid. Under Developers and API keys you can only create test keys, and they never work against the live account. Sandbox records are sample data kept apart from live data, so what you do here does not change customers, invoices or payments in the live account.
Common problems#
- You see An account already uses this email or phone. Sign in to that account. That contact already has an account. Click Sign in, then use Switch to sandbox in the Your account menu.
- The menu has no Switch to sandbox: your plan does not include Sandbox workspaces, or you are not a member of the sandbox. Ask the Owner to check the plan or your access.
- You see Only test keys can be created in the sandbox. You tried to create a live key inside the sandbox. Exit the sandbox to create live keys.
gotactl sandbox advancereturns 403: the command only works in a sandbox. Check that the CLI is using the sandbox context, not the live one.