Skip to main content

Getting started

The Kosoor Merchant API lets your system work with a Kosoor merchant's data: its customers, sales invoices, payments and credit notes.

Base URL​

https://api.kosoor.com.sa

Every path starts with /v1. Requests and responses are JSON with camelCase names, over HTTPS.

Get a key​

The merchant creates the key in the Kosoor dashboard, on the API keys screen, and gives it to you. A key belongs to one merchant, carries only the permissions the merchant granted, and may be limited to some of its branches. See Authentication.

Your first request​

curl https://api.kosoor.com.sa/v1/customers?limit=1 \
  -H "Authorization: Bearer ksr_live_..."
{
  "data": [],
  "hasMore": false
}

Every object names its kind​

Every object the API returns carries object, a fixed string naming what it is: customer, salesInvoice, payment or creditNote. One kind always has the same value. Read it wherever one part of your code receives more than one kind, such as stored replies or logs, instead of guessing from the URL or from which fields are present.

{
  "id": "3f1c2a6e-8b4d-4e2a-9c1f-5d7e8a9b0c12",
  "object": "salesInvoice",
  "number": "INV-1042"
}

On every request​

  • Request-Id: every response carries one, success or failure. Quote it when you contact Kosoor about a call.
  • Language: send Accept-Language: ar for Arabic messages; anything else answers in English. Only messages change, never codes or field names.
  • Strict input: a body field or query parameter the endpoint does not know is refused with unknown_parameter, so a typo never passes silently.
  • Body: Content-Type: application/json, at most 1 MB.
  • Writes: every POST and PATCH carries an Idempotency-Key, so a retry never creates a second record. See Retries and idempotency.
  • Errors: one body shape for every failure, with a stable code. See Error codes.