Endpoints
/api/v1/invoices
/api/v1/customers
/api/v1/customers
/api/v1/customers/{id}
/api/v1/customers/{id}
An existing customer, by id
Send the id of a customer of your company. An id that belongs to another company is answered exactly like one that does not exist: 422 customer_not_found.
{
"issue_date": "2026-11-03",
"customer": { "id": 381 },
"items": [{ "description": "Monthly plan", "quantity": 1, "unit_price": 99 }]
}An inline customer
Send the buyer's details instead of an id and WonderFatoora saves them as a new customer (your plan's customer limit applies). A buyer with a VAT number is saved as a business, one without as an individual. Inline creation needs only invoices:write.
{
"issue_date": "2026-11-03",
"customer": {
"name": "Example Trading Co.",
"vat_number": "300000000000003",
"email": "billing@example.com",
"phone": "0500000000",
"address_line1": "King Fahd Rd",
"city": "Riyadh",
"postal_code": "12345",
"country": "SA"
},
"items": [{ "description": "Monthly plan", "quantity": 1, "unit_price": 99 }]
}data.invoice.customer.id from the response against your own customer record, and send {"id": …} next time to avoid duplicates.
No customer
Leave customer out, or send no name, for a sale to an unnamed consumer. The invoice is a simplified tax invoice.
Business buyers and ZATCA
An invoice to a buyer with a valid Saudi VAT number is a standard tax invoice. For a company linked to ZATCA it is cleared before it reaches the buyer, and ZATCA requires the buyer's full national address:
| Part | Rule |
|---|---|
| Street | Required |
| Building number | 4 digits |
| District | Required |
| City | Required |
| Postal code | 5 digits |
Inline details on an invoice cannot carry the building number or the district. For business buyers, create the customer once with POST /customers (or in the dashboard) with the full address and send its id. A buyer outside Saudi Arabia needs a street and a city.
VAT numbers
A Saudi VAT number has 15 digits and starts and ends with 3; a malformed one is refused with 422. For a buyer outside Saudi Arabia, set country to its ISO code (for example AE) and send that buyer's own tax number, which is not held to the Saudi format.
customers:read to list and read, and customers:write to create and update. Email, mobile and VAT number are unique within your company. See the API reference.
Related
Ready to build?
API access is part of the Business and Enterprise plans. Create a key in Settings → API keys and make your first call in minutes.