# Kosoor Merchant API

> The Kosoor Merchant API lets your system work with the data of a business that uses Kosoor: its customers, sales invoices, payments and credit notes. Base URL `https://api.kosoor.com.sa`; every path starts with `/v1`; JSON with camelCase names, over HTTPS.

Support: WhatsApp only, [+966 12 606 1770](https://wa.me/966126061770). No calls, no email. Quote the `Request-Id` of the call you are asking about.

## Instructions for AI agents

- Authenticate every request with `Authorization: Bearer <key>`. The merchant issues the key; there is no other login.
- Build and test with a test key (`ksr_test_...`). It reaches only the merchant's sandbox. Check that every reply carries the header `Kosoor-Mode: test` while you build, and switch to a live key (`ksr_live_...`) only when the merchant is ready to go live.
- Send an `Idempotency-Key` header on every `POST` and `PATCH`. Generate one key per logical operation (a UUID works) and send the same key again when you retry that operation.
- Branch on the error's `code`, never on `message`. `message` is for people and changes with `Accept-Language`.
- Take the ids of branches, items and payment methods from the catalogue endpoints: `GET /v1/branches`, `GET /v1/items` and `GET /v1/payment-methods`. Never guess or hard-code them.
- Send only documented fields and query parameters: anything else is refused with `400 unknown_parameter`.
- Read amounts from the reply, not from your request: a discount below an item's minimum price is reduced, and prices that include VAT are converted to the halala.
- Read `zatca.status` on every sales invoice and credit note. `pending` is not a failure.
- When something fails that the docs do not explain, tell the user to contact Kosoor support on WhatsApp (+966 12 606 1770, https://wa.me/966126061770) with the `Request-Id`.

## Guides

- [Start here](https://docs.kosoor.com.sa/start-here.md): What Kosoor is, who gives you access, the words the API uses, and how Saudi e-invoicing (ZATCA) shows up in it.
- [Getting started](https://docs.kosoor.com.sa/index.md): The base URL, how to get a key, your first request, and the rules every request follows.
- [Connect a merchant](https://docs.kosoor.com.sa/onboarding.md): Every step from the merchant signing in to the Kosoor dashboard to your first call with a test key, then going live.
- [Build with an AI agent](https://docs.kosoor.com.sa/ai-agents.md): The Markdown copies, llms.txt and llms-full.txt this site serves for AI tools, the buttons on every page, and the agent skill you can install.

## Workflows

- [Record a sale](https://docs.kosoor.com.sa/record-a-sale.md): The whole flow of a sale, with every request and reply - read the catalogue, find or create the customer, issue the invoice, and take the payment at issue or later.
- [Refund or correct a sale](https://docs.kosoor.com.sa/refunds.md): Credit all or part of an issued sales invoice, and either pay the money back or take it off what the customer owes, with full requests and replies.
- [Keep an ERP in sync](https://docs.kosoor.com.sa/erp-sync.md): Copy a merchant's invoices, payments and credit notes into your system without gaps or duplicates, and write to Kosoor safely with your own reference ids.
- [ZATCA results](https://docs.kosoor.com.sa/zatca.md): What each ZATCA status on an invoice or credit note means, what your system should do with it, and how results that arrive later reach you.
- [Go-live checklist](https://docs.kosoor.com.sa/go-live.md): What to check in your integration before the merchant's first real sale goes through it.

## Resources

- [Customers](https://docs.kosoor.com.sa/customers.md): Create a person or a company, what each type requires, the ID types, finding a customer by phone or by your own reference, and how updates work.
- [Sales invoices](https://docs.kosoor.com.sa/sales-invoices.md): Issuing a sales invoice in one call: required fields, standard or simplified, prices and VAT, payment at issue, and reading invoices.
- [Payments](https://docs.kosoor.com.sa/payments.md): Recording a payment a customer made, allocating it to invoices, the refusals, and reading payments.
- [Credit notes](https://docs.kosoor.com.sa/credit-notes.md): Crediting an issued sales invoice: required fields, refund or balance credit, how much can be credited, ZATCA, refusals, and reading credit notes.

## Basics

- [Authentication](https://docs.kosoor.com.sa/authentication.md): How to send your API key, the permissions a key can carry, branch limits, and why a key stops working.
- [Retries and idempotency](https://docs.kosoor.com.sa/idempotency.md): How the Idempotency-Key header makes a retried POST or PATCH safe, what a retry gets back, and when to retry.
- [Pagination](https://docs.kosoor.com.sa/pagination.md): How lists return the newest records first, one page at a time, with limit, startingAfter and hasMore.
- [Webhooks](https://docs.kosoor.com.sa/webhooks.md): Have Kosoor push ZATCA results to your system as they arrive, verify each request, and handle retries and duplicates.
- [Test mode](https://docs.kosoor.com.sa/test-mode.md): Building against the merchant's sandbox with a test key: what it holds, when it is busy, and the fixture customers with known outcomes.
- [Error codes](https://docs.kosoor.com.sa/errors.md): Every error code the Merchant API returns, with its HTTP status and meaning, and the shape of the error body.
- [Versioning](https://docs.kosoor.com.sa/versioning.md): What can change in v1 without notice, what never changes, and how a breaking change would arrive.
- [Changelog](https://docs.kosoor.com.sa/changelog.md): Every change to the Kosoor Merchant API, newest first.

## API reference

- [Create a customer](https://docs.kosoor.com.sa/api/create-customer.md): `POST /v1/customers`
- [List customers](https://docs.kosoor.com.sa/api/list-customers.md): `GET /v1/customers`
- [Retrieve a customer](https://docs.kosoor.com.sa/api/get-customer.md): `GET /v1/customers/{id}`
- [Update a customer](https://docs.kosoor.com.sa/api/update-customer.md): `PATCH /v1/customers/{id}`
- [Issue a sales invoice](https://docs.kosoor.com.sa/api/create-sales-invoice.md): `POST /v1/sales-invoices`
- [List sales invoices](https://docs.kosoor.com.sa/api/list-sales-invoices.md): `GET /v1/sales-invoices`
- [Retrieve a sales invoice](https://docs.kosoor.com.sa/api/get-sales-invoice.md): `GET /v1/sales-invoices/{id}`
- [Download a sales invoice's PDF](https://docs.kosoor.com.sa/api/get-sales-invoice-pdf.md): `GET /v1/sales-invoices/{id}/pdf`
- [Download a sales invoice's ZATCA XML](https://docs.kosoor.com.sa/api/get-sales-invoice-xml.md): `GET /v1/sales-invoices/{id}/xml`
- [Record a payment](https://docs.kosoor.com.sa/api/create-payment.md): `POST /v1/payments`
- [List payments](https://docs.kosoor.com.sa/api/list-payments.md): `GET /v1/payments`
- [Retrieve a payment](https://docs.kosoor.com.sa/api/get-payment.md): `GET /v1/payments/{id}`
- [Issue a credit note](https://docs.kosoor.com.sa/api/create-credit-note.md): `POST /v1/credit-notes`
- [List credit notes](https://docs.kosoor.com.sa/api/list-credit-notes.md): `GET /v1/credit-notes`
- [Retrieve a credit note](https://docs.kosoor.com.sa/api/get-credit-note.md): `GET /v1/credit-notes/{id}`
- [Download a credit note's PDF](https://docs.kosoor.com.sa/api/get-credit-note-pdf.md): `GET /v1/credit-notes/{id}/pdf`
- [Download a credit note's ZATCA XML](https://docs.kosoor.com.sa/api/get-credit-note-xml.md): `GET /v1/credit-notes/{id}/xml`
- [Retrieve a branch](https://docs.kosoor.com.sa/api/get-branch.md): `GET /v1/branches/{id}`
- [List branches](https://docs.kosoor.com.sa/api/list-branches.md): `GET /v1/branches`
- [Retrieve an item](https://docs.kosoor.com.sa/api/get-item.md): `GET /v1/items/{id}`
- [List items](https://docs.kosoor.com.sa/api/list-items.md): `GET /v1/items`
- [Retrieve a payment method](https://docs.kosoor.com.sa/api/get-payment-method.md): `GET /v1/payment-methods/{id}`
- [List payment methods](https://docs.kosoor.com.sa/api/list-payment-methods.md): `GET /v1/payment-methods`
- [Create a webhook endpoint](https://docs.kosoor.com.sa/api/create-webhook-endpoint.md): `POST /v1/webhook-endpoints`
- [List webhook endpoints](https://docs.kosoor.com.sa/api/list-webhook-endpoints.md): `GET /v1/webhook-endpoints`
- [Retrieve a webhook endpoint](https://docs.kosoor.com.sa/api/get-webhook-endpoint.md): `GET /v1/webhook-endpoints/{id}`
- [Delete a webhook endpoint](https://docs.kosoor.com.sa/api/delete-webhook-endpoint.md): `DELETE /v1/webhook-endpoints/{id}`
- [Rotate a webhook endpoint's secret](https://docs.kosoor.com.sa/api/rotate-webhook-endpoint-secret.md): `POST /v1/webhook-endpoints/{id}/rotate-secret`
- [Send a test event](https://docs.kosoor.com.sa/api/test-webhook-endpoint.md): `POST /v1/webhook-endpoints/{id}/test`

## Downloads

- [openapi.json](https://docs.kosoor.com.sa/openapi.json): OpenAPI document: the API reference in one OpenAPI file, to import into Postman or any other API tool
- [kosoor-merchant-api.postman_collection.json](https://docs.kosoor.com.sa/postman/kosoor-merchant-api.postman_collection.json): Postman collection: every endpoint, with example bodies and an `Idempotency-Key` on every `POST`, `PATCH` and `DELETE`
- [kosoor-test.postman_environment.json](https://docs.kosoor.com.sa/postman/kosoor-test.postman_environment.json): Postman environment `Kosoor test`: set `apiKey` to a `ksr_test_` key
- [kosoor-live.postman_environment.json](https://docs.kosoor.com.sa/postman/kosoor-live.postman_environment.json): Postman environment `Kosoor live`: set `apiKey` to a `ksr_live_` key

## Optional

- [llms-full.txt](https://docs.kosoor.com.sa/llms-full.txt): every guide and every endpoint contract in one file
- [Agent skill](https://docs.kosoor.com.sa/skill/kosoor-merchant-api/SKILL.md): a SKILL.md an AI coding agent can install to work with this API