API changelog

November 2026

• Invoices that arrive paid: the optional payment field of POST /invoices records the payment as the invoice is issued, for a site whose own gateway takes the money first. Needs the payments:write scope. Details.
• Two new endpoints: GET /invoices/{id}/payments and POST /invoices/{id}/payments.
• Two new error codes: invoice_not_payable (409) and payment_exceeds_balance (422).
• Additive: an existing integration that changes nothing is not affected.

October 2026

• Developer documentation published at /developers, in Arabic and English, with the OpenAPI 3.1 document at /developers/openapi.json.
• New endpoints: company profile and readiness, customers, invoice list, status, validate, issue, PDF and XML, and credit and debit notes.
• New scopes: companies:read, customers:read, customers:write, invoices:draft, invoices:download and webhooks:manage. Keys with invoices:write keep working.
• An Idempotency-Key header on every write.
• Signed webhooks and GET /events.
• Sandbox companies with test keys (wbk_test_…) and simulated ZATCA results.
• OAuth 2.1 app connections, and Wonder Fatoora MCP for AI agents.
• MCP tools for products and services (search_products, get_product, create_product, update_product) and for customer payments (record_payment, list_invoice_payments), with the new scopes products:read, products:write and payments:write.
• Rate limits per company by plan, with separate budgets for issuing and downloads.
• An expired API key answers 401 token_expired, with details.expired_at and details.renew_url; every other refusal is unchanged. A reminder email goes out 14 and 3 days before a live key expires.

September 2026

• Keys carry scopes: invoices:read, invoices:write and invoices:issue. Issuing needs invoices:issue.
• Keys expire (30, 90, 180 or 365 days) and can be rotated.
• Per-key rate limits: 60 requests a minute and 5,000 a day, answered with 429 rate_limited and Retry-After.
• Invoices include a zatca object: flow, status, warnings, UUID, deliverability and ZATCA's messages.
• Drafts carry a DRAFT-… reference and number_is_final: false; the legal number is assigned at issue.
• Lines accept vat_exemption_code and vat_exemption_reason for zero-rated and exempt sales.
• external_reference makes invoice creation safe to retry.

July 2026

• Invoices in USD and AED, with an exchange_rate to SAR.

June 2026

• API v1: GET /ping, POST /invoices and GET /invoices/{id}.

Coming next

The official SDKs are built and tested, and not published yet.