# Changelog

> Every change to the Kosoor Merchant API, newest first.

Every change to the API is listed here, newest first. See [Versioning](https://docs.kosoor.com.sa/versioning.md) for what can change within v1.

## 7 November 2026: v1

The first version of the Merchant API.

- **Customers**: create, read, list and update people and companies; find them by phone, VAT number, ID or your own `referenceId`. Permissions `customers:read` and `customers:write`. See [Customers](https://docs.kosoor.com.sa/customers.md).
- **Sales invoices**: issue an invoice in one call, with payment at issue or on account; standard invoices are cleared by ZATCA before the reply. Read and list invoices from every channel, and download their PDF and ZATCA XML. Permissions `sales_invoices:read` and `sales_invoices:write`. See [Sales invoices](https://docs.kosoor.com.sa/sales-invoices.md).
- **Payments**: record a payment and allocate it to invoices; read and list payments from every channel. Permissions `payments:read` and `payments:write`. See [Payments](https://docs.kosoor.com.sa/payments.md).
- **Credit notes**: credit an issued invoice with a refund or against what the customer owes; read and list credit notes, including refunds made at the POS and on the dashboard; download their PDF and ZATCA XML. Permissions `credit_notes:read` and `credit_notes:write`. See [Credit notes](https://docs.kosoor.com.sa/credit-notes.md).
- **Catalogue**: read and list branches, items and payment methods, to fill the IDs an invoice needs. Permissions `branches:read`, `items:read` and `payment_methods:read`.
- **Webhooks**: ZATCA results that arrive after the reply are pushed to an HTTPS endpoint the key registers, signed the Standard Webhooks way and retried for about 3 days. Permissions `webhooks:read` and `webhooks:write`. See [Webhooks](https://docs.kosoor.com.sa/webhooks.md).
- **Test mode**: a sandbox per merchant, test keys that start with `ksr_test_`, the `Kosoor-Mode: test` header and fixture customers with known outcomes. See [Test mode](https://docs.kosoor.com.sa/test-mode.md).
- **Rate limits**: per API key, in a fixed one-minute window, reads and writes counted apart: 1,200 reads and 300 writes for a live key, 300 and 60 for a test key. Past them, `429 rate_limited` with `Retry-After`. See [Rate limits](https://docs.kosoor.com.sa/errors.md#rate_limit_error).
- **Downloads**: the [OpenAPI document](https://docs.kosoor.com.sa/openapi.json), and a [Postman collection](https://docs.kosoor.com.sa/postman/kosoor-merchant-api.postman_collection.json) with the [Kosoor test](https://docs.kosoor.com.sa/postman/kosoor-test.postman_environment.json) and [Kosoor live](https://docs.kosoor.com.sa/postman/kosoor-live.postman_environment.json) environments.

Source: https://docs.kosoor.com.sa/changelog