Start here
Read this page first if you have never worked with Kosoor or with Saudi e-invoicing.
What Kosoor is
Kosoor is a point-of-sale and business system for businesses in Saudi Arabia, many of them car washes and service centres. A business sells through Kosoor at the POS, at a self-service kiosk, on its online store and on the Kosoor dashboard. Kosoor keeps its customers, invoices, payments and accounts, and sends its invoices to ZATCA, the Saudi tax authority.
The Merchant API lets another system read and write that data: customers, sales invoices, payments and credit notes.
Merchant and partner
- Merchant: a business that uses Kosoor. Its data lives in its own Kosoor account.
- Partner: you. Your company builds a system, such as an ERP, a booking app or a fleet portal, that works with a merchant's data through this API.
A key belongs to one merchant. To work with several merchants, you hold one key per merchant.
How access works
- The merchant issues an API key in the Kosoor dashboard, under Settings → Developers, and gives it to you. Connect a merchant walks through it.
- You send the key with every request. The key alone tells Kosoor which merchant the call is for: you send no merchant id, and you need no Kosoor account or login of your own.
- The key carries only the permissions the merchant granted, and may be limited to some of the merchant's branches. The merchant can revoke it at any time.
There are two kinds of key. A test key (ksr_test_...) reaches only the merchant's sandbox, a separate copy of its catalogue; build with it. A live key (ksr_live_...) reaches the merchant's real data. See Test mode.
Words the API uses
| Term | Meaning |
|---|---|
| Branch | One of the merchant's locations, such as a shop or a service centre. Every invoice and payment belongs to a branch, and a key may be limited to some branches. |
| Item | Something the merchant sells: a product, a service or a subscription. An invoice line names an item by its id. |
| POS | The point of sale in a branch, where a cashier takes the money. A sale made there shows createdVia: "pos" in the API. |
| Payment method | How a customer pays, as the merchant set it up, such as cash or card. |
| Treasury | Where money sits in the merchant's books, such as a cash box or a bank account. Each payment method pays into a treasury, which can differ by branch. |
| Cost centre | A tag the merchant's accountant uses to group income and costs, such as a department or a project. An invoice can carry one in costCentreId. |
| Car size | Many merchants price a service by the size of the car. An item priced per car size has no single catalogue price, so an invoice line for it must send unitPrice. |
| Subscription | A package of visits a customer buys, such as a number of car washes. The API does not sell subscriptions: a line naming one answers 422 item_not_sellable. |
| Customer | A person or a company. Every invoice made through the API names one. |
| SAR | The Saudi riyal. Every amount in the API is in SAR (currency: "SAR"). |
| Halala | One hundredth of a riyal. Kosoor keeps amounts to the halala, so at most two decimals. |
| VAT | Value added tax. The standard rate in Saudi Arabia is 15%. Each item carries its own rate in Kosoor, and each invoice line shows it in vatRate, for example 15. |
| VAT number | A business's VAT registration number: 15 digits that start and end with 3. |
| Commercial registration (CR) | A company's registration number in Saudi Arabia. A company customer with no VAT number can be identified by it instead (idType: "CRN"). |
ZATCA in five minutes
ZATCA is the Zakat, Tax and Customs Authority. Its e-invoicing system, Fatoora, receives every invoice and credit note a Saudi business issues. Kosoor does that part for the merchant: you never call ZATCA, sign XML or build a QR code. You only read the result.
Standard and simplified
ZATCA has two kinds of invoice, and in Kosoor the customer decides which one an invoice is:
| Standard (tax invoice) | Simplified | |
|---|---|---|
| Customer | a company | a person |
| ZATCA's process | clearance: ZATCA checks the invoice and clears it before the buyer gets it | reporting: the invoice is issued first, then reported to ZATCA |
| In the API | Kosoor clears it before it replies to you | Kosoor reports it after it replies to you |
zatca.kind in the reply says which one it is: standard or simplified. A credit note is the same kind as the invoice it credits.
What each status means
zatca.status | Meaning |
|---|---|
pending | ZATCA has not accepted the document yet. A simplified document is pending until Kosoor reports it. A standard one is pending only when ZATCA did not answer in time; Kosoor sends it again later. |
cleared | ZATCA cleared this standard document. zatca.qr holds the QR code ZATCA returned. |
reported | ZATCA accepted the report of this simplified document. |
rejected | ZATCA refused the document. Its messages are in zatca.errors. |
pending is not a failure. The document is issued, and its number and amounts do not change. A standard document that ZATCA rejects while Kosoor clears it is not saved at all: the call answers 422 zatca_rejected. So a saved document turns rejected only after it was pending.
What to do with each status is in ZATCA results. In the sandbox, documents are signed with ZATCA's test certificates and never reach the merchant's real ZATCA records.
Where to go next
- Getting started: the base URL and the rules every request follows.
- Connect a merchant: from the merchant's dashboard to your first call.
- Record a sale: the whole flow, with every request and reply.