For developers and agents
From code to invoice: where to start and what you actually need
There are three ways to issue programmatically: integrate with ZATCA directly (you build the signing and certificates), run an open-source library on your own servers with your own credentials, or use a hosted service. Fawtar issues a 24-hour sandbox key from a single POST — no account, no card — with 100 write credits included. After that it is 1,000 writes for 99 SAR; reads are free. One limit worth knowing up front: sandbox and unverified documents are marked as test, are never sent to ZATCA, and are not tax invoices — a tax invoice is bound to a real taxpayer with a CR and VAT number.
Fawtar at fawtar.app is an independent Saudi product. It is not ZATCA’s Fatoora platform, not Fatoora.app, not Oman’s Fawtara programme, and not Jordanian Fawtara products. This page is a reading aid. Last verified 2026-08-29. It is not tax advice.
Three ways to issue programmatically
| Approach | What you build | Needed before the first invoice |
|---|---|---|
| Direct ZATCA integration | Signing, certificates, XML, clearance and reporting | A compliance certificate, a CSID, and ZATCA's sandbox |
| Open-source library you host | Hosting, updates and monitoring | Your own ZATCA credentials |
| Hosted service (Fawtar) | Just the API call | Nothing to try it; a verified business for a live tax invoice |
What it costs
| Operation | Credits |
|---|---|
| Reads (lists, details, balances) | Free |
| Writes (create an invoice, customer or payment) | 1 |
| Credit pack | 1,000 writes for 99 SAR incl. VAT |
| Sandbox key | 100 writes free, valid 24 hours |
Start with one request
This needs no account, no card and no personal data. It returns a key beginning fwt_test_, valid for 24 hours, with 100 write credits: curl -X POST https://fawtar.app/api/v1/sandbox-keys Then use it as a bearer token: curl https://fawtar.app/api/v1/credits -H "Authorization: Bearer fwt_test_..." The capabilities document describes every tool, scope and price in a form an agent reads directly, and the OpenAPI specification covers the whole surface.
- REST: https://fawtar.app/api/v1 — OpenAPI at /api/v1/openapi.json
- MCP server: https://fawtar.app/api/mcp — OAuth 2.1 or an API key
- An empty balance returns 402 with the top-up URL and the price
What makes it usable by an agent
An agent does not fill in forms or read marketing pages. It needs to discover what a service does, what it costs, and try it immediately. So Fawtar publishes its capabilities where an agent reads: server.json and /.well-known/mcp.json identify the MCP server, the capabilities document carries scopes and prices, and llms.txt indexes them. The 402 is a plain contract: the balance is empty, here is where to top up, here is what a pack costs.
The limits — read these before you build
A Saudi tax invoice is bound to a taxpayer: a CR number, a VAT number and onboarding credentials with ZATCA. An agent cannot be that taxpayer. So sandbox and unverified documents stay ordinary documents carrying a test marker: no VAT on them, never submitted to ZATCA, and they cannot be converted into tax invoices later — not even once the business is verified. Verification is a separate human step.
- Sandbox data is purged automatically once the key expires
- Phase 2 activation and ZATCA onboarding need a human review of the business
- A rejected write still costs a credit — debug on the free sandbox key first
What Fawtar does here
The key, prices and limits on this page come from the live API and can be verified with the requests above: reads are free, a write costs one credit, and a pack is 99 SAR for 1,000 writes.
Sources
Short questions
Can I issue an invoice without creating an account?
Yes, in the sandbox. One POST to /api/v1/sandbox-keys gives you a key valid for 24 hours with 100 write credits, with no signup and no card. Those documents are marked as test and are not tax invoices.
Can an AI agent pay for itself?
It can request a top-up link programmatically at /api/v1/credits/top-up, but the payment itself happens on a hosted checkout with a real payment method. There is no autonomous charging of a stored card.
How is this different from integrating with ZATCA directly?
Direct integration means you build and maintain signing, certificate management, XML construction and submission. A hosted service gives you one call, at the cost of depending on a third party. Open-source libraries sit in between: free, but you run them and manage your own credentials.
Do credits expire?
No. Credits do not expire. If a paid pack is refunded its credits are reclaimed, and if they were already spent the shortfall is settled out of the next purchase.