Sandbox

What a sandbox is

A sandbox company is a test company you create yourself, linked to your real company and separate from it. You open it with the company switcher, like any company you belong to, and your real company is never changed.

• It comes with demo data: five customers (among them Demo B2B Co., with a full national address, and a foreign buyer), five products, three draft invoices, two issued invoices and a credit note. Find them with GET /customers?q=Demo.
• Its numbers start with TEST-INV- and TEST-CN-, and its seller VAT number is plainly fake.
• It is free and never billed, with its own limits: 300 invoices a month, 100 customers and 3 users.

Create one

1. Sign in and open Settings → Developers → Sandbox in your own company. You need permission to manage the company's settings.
2. Choose Create a sandbox company. You can keep up to two.
3. Open it, then create a key under Settings → Developers → API keys. A sandbox key starts with wbk_test_.

Reset empties the sandbox and seeds the demo data again; its keys stay. Delete removes it with all its data. A sandbox nobody uses for 90 days is deleted, a week after an email warning.

Test keys and live keys never mix

A key minted in a sandbox is a test key (wbk_test_…) and works only on that sandbox. A live key (wbk_…) never works on a sandbox. Either one used against the other kind of company gets 401 unauthorized.

Simulated ZATCA results

Sandbox invoices and notes are never sent to ZATCA. Each issued document gets a simulated result instead, in the same vocabulary as a live company: zatca.status is pending at first and becomes cleared (a buyer with a VAT number, or an export) or reported (anyone else) about a minute later.

Put a marker in a line description to test the other outcomes:

• [sandbox:reject]: rejected, with sample messages in zatca.errors.
• [sandbox:warning]: cleared or reported, with with_warnings: true.
• [sandbox:retry]: retrying first, then cleared or reported a minute later.

Nothing leaves a sandbox

• No email or WhatsApp message reaches a customer. Only you, the sandbox's owner, can receive an email from it.
• No payment link or subscription checkout.
• Its PDFs are marked SANDBOX and print no QR code. Nothing in a sandbox is a tax invoice.

Try-it console

An in-browser console is planned for sandbox keys only, enforced both in the browser and by the API. Until it exists, these docs never ask you to paste a key into a web page.