Quotations

Create a quotation

POST/quotations

Needs

sales.write

Scopes

sales:write

Send an Idempotency-Key header.

A draft quotation. Lines name a product by productId or productCode (SKU, then barcode). Requires Idempotency-Key.

Parameters

Request body

Code samples

curl -sS -X POST "https://app.kwn.tax/api/v1/quotations" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "cus_4kq9w2m1",
  "issueDate": "2026-10-15",
  "dueDate": "2026-11-14",
  "customerRef": "PO-7781",
  "externalId": "SO-10045",
  "lines": [
    {
      "description": "Office chair, mesh back",
      "quantity": 4,
      "unitPrice": 450,
      "taxRate": 5,
      "productCode": "CHR-MESH-01"
    },
    {
      "description": "Delivery within Dubai",
      "quantity": 1,
      "unitPrice": 100,
      "taxRate": 5
    }
  ]
}'

Responses

• 201Created

  Field	Type	Description
  id	string
  type	QUOTATION | ORDER | INVOICE | CREDIT_NOTE | DEBIT_NOTE
  number	string
  status	DRAFT | SENT | CONFIRMED | ISSUED | SUBMITTED | PROCESSING | APPROVED | REJECTED | FAILED | PAID | CANCELLED | EXPIRED
  issueDate	date
  dueDate	date
  expiryDate	date
  customer	object
  emirate	ABU_DHABI | DUBAI | SHARJAH | AJMAN | UMM_AL_QUWAIN | RAS_AL_KHAIMAH | FUJAIRAH
  currency	string
  taxMode	TAX_EXCLUDED | TAX_INCLUDED
  customerRef	string
  notes	string
  paymentTermId	string
  fiscalPositionId	string
  salespersonId	string
  salesTeamId	string
  invoiceAddressId	string
  deliveryAddressId	string
  lines	object[]
  subtotal	number
  discountTotal	number
  taxTotal	number
  total	number
  invoicedTotal	number
  paidTotal	number
  creditedTotal	number
  source	object
  derived	object[]
  origin	string	API, MANUAL, ODOO or POS.
  externalId	string
  clearance	object
  eInvoice	object
  createdAt	date
  updatedAt	date

• 400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).

  ExampleCopy

  {
    "error": "Lines: at least one line is required.",
    "code": "REQUEST_INVALID"
  }

• 401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).

  ExampleCopy

  {
    "error": "That API key is not valid, or it was revoked.",
    "code": "API_KEY_INVALID"
  }

• 403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).

  ExampleCopy

  {
    "error": "This key's scopes do not include sales.approve.",
    "code": "ROLE_TOO_LOW"
  }

• 404Not found: another type under this route, or another company's (NOT_FOUND).

  ExampleCopy

  {
    "error": "Not found.",
    "code": "NOT_FOUND"
  }

• 409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

  ExampleCopy

  {
    "error": "That externalId is already used by another record of this company.",
    "code": "EXTERNAL_ID_TAKEN"
  }

• 422That Idempotency-Key was used for a different request (IDEMPOTENCY_KEY_REUSED).

  ExampleCopy

  {
    "error": "That Idempotency-Key was used for a different request.",
    "code": "IDEMPOTENCY_KEY_REUSED"
  }

• 429Too many requests: wait retryAfter seconds (RATE_LIMITED).

  ExampleCopy

  {
    "error": "Too many requests. Wait a little and try again.",
    "code": "RATE_LIMITED"
  }

List

GET/quotations

Needs

sales.read

Scopes

sales:read

Newest first, a page at a time: send the previous page's next as cursor. Filter by status, partnerId (the customer), issueFrom/issueTo, number, externalId, createdFrom/createdTo, or updatedSince to poll for changes.

Parameters

Code samples

curl -sS -X GET "https://app.kwn.tax/api/v1/quotations" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

• 200OK

  Field	Type	Description
  data	object[]	The rows of this page.
  next	string	The cursor of the next page, to send as ?cursor=; null on the last page.

• 400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).

  ExampleCopy

  {
    "error": "Lines: at least one line is required.",
    "code": "REQUEST_INVALID"
  }

• 401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).

  ExampleCopy

  {
    "error": "That API key is not valid, or it was revoked.",
    "code": "API_KEY_INVALID"
  }

• 403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).

  ExampleCopy

  {
    "error": "This key's scopes do not include sales.approve.",
    "code": "ROLE_TOO_LOW"
  }

• 404Not found: another type under this route, or another company's (NOT_FOUND).

  ExampleCopy

  {
    "error": "Not found.",
    "code": "NOT_FOUND"
  }

• 409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

  ExampleCopy

  {
    "error": "That externalId is already used by another record of this company.",
    "code": "EXTERNAL_ID_TAKEN"
  }

• 429Too many requests: wait retryAfter seconds (RATE_LIMITED).

  ExampleCopy

  {
    "error": "Too many requests. Wait a little and try again.",
    "code": "RATE_LIMITED"
  }

Update a quotation

PUT/quotations/{id}

Needs

sales.write

Scopes

sales:write

Replaces the header and the lines of a quotation that is still a draft or sent.

Parameters

Request body

Code samples

curl -sS -X PUT "https://app.kwn.tax/api/v1/quotations/<id>" \
  -H "X-Api-Key: $KWN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customerId": "cus_4kq9w2m1",
  "issueDate": "2026-10-15",
  "dueDate": "2026-11-14",
  "customerRef": "PO-7781",
  "externalId": "SO-10045",
  "lines": [
    {
      "description": "Office chair, mesh back",
      "quantity": 4,
      "unitPrice": 450,
      "taxRate": 5,
      "productCode": "CHR-MESH-01"
    },
    {
      "description": "Delivery within Dubai",
      "quantity": 1,
      "unitPrice": 100,
      "taxRate": 5
    }
  ]
}'

Responses

• 200OK

  Field	Type	Description
  id	string
  type	QUOTATION | ORDER | INVOICE | CREDIT_NOTE | DEBIT_NOTE
  number	string
  status	DRAFT | SENT | CONFIRMED | ISSUED | SUBMITTED | PROCESSING | APPROVED | REJECTED | FAILED | PAID | CANCELLED | EXPIRED
  issueDate	date
  dueDate	date
  expiryDate	date
  customer	object
  emirate	ABU_DHABI | DUBAI | SHARJAH | AJMAN | UMM_AL_QUWAIN | RAS_AL_KHAIMAH | FUJAIRAH
  currency	string
  taxMode	TAX_EXCLUDED | TAX_INCLUDED
  customerRef	string
  notes	string
  paymentTermId	string
  fiscalPositionId	string
  salespersonId	string
  salesTeamId	string
  invoiceAddressId	string
  deliveryAddressId	string
  lines	object[]
  subtotal	number
  discountTotal	number
  taxTotal	number
  total	number
  invoicedTotal	number
  paidTotal	number
  creditedTotal	number
  source	object
  derived	object[]
  origin	string	API, MANUAL, ODOO or POS.
  externalId	string
  clearance	object
  eInvoice	object
  createdAt	date
  updatedAt	date

• 400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).

  ExampleCopy

  {
    "error": "Lines: at least one line is required.",
    "code": "REQUEST_INVALID"
  }

• 401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).

  ExampleCopy

  {
    "error": "That API key is not valid, or it was revoked.",
    "code": "API_KEY_INVALID"
  }

• 403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).

  ExampleCopy

  {
    "error": "This key's scopes do not include sales.approve.",
    "code": "ROLE_TOO_LOW"
  }

• 404Not found: another type under this route, or another company's (NOT_FOUND).

  ExampleCopy

  {
    "error": "Not found.",
    "code": "NOT_FOUND"
  }

• 409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

  ExampleCopy

  {
    "error": "That externalId is already used by another record of this company.",
    "code": "EXTERNAL_ID_TAKEN"
  }

• 429Too many requests: wait retryAfter seconds (RATE_LIMITED).

  ExampleCopy

  {
    "error": "Too many requests. Wait a little and try again.",
    "code": "RATE_LIMITED"
  }

Read one

GET/quotations/{id}

Needs

sales.read

Scopes

sales:read

The document with its lines, where it came from and what came of it, its e-invoice readiness and, for an invoice or credit note, its clearance. A document of another type under this route is NOT_FOUND.

Parameters

Code samples

curl -sS -X GET "https://app.kwn.tax/api/v1/quotations/<id>" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

• 200OK

  Field	Type	Description
  id	string
  type	QUOTATION | ORDER | INVOICE | CREDIT_NOTE | DEBIT_NOTE
  number	string
  status	DRAFT | SENT | CONFIRMED | ISSUED | SUBMITTED | PROCESSING | APPROVED | REJECTED | FAILED | PAID | CANCELLED | EXPIRED
  issueDate	date
  dueDate	date
  expiryDate	date
  customer	object
  emirate	ABU_DHABI | DUBAI | SHARJAH | AJMAN | UMM_AL_QUWAIN | RAS_AL_KHAIMAH | FUJAIRAH
  currency	string
  taxMode	TAX_EXCLUDED | TAX_INCLUDED
  customerRef	string
  notes	string
  paymentTermId	string
  fiscalPositionId	string
  salespersonId	string
  salesTeamId	string
  invoiceAddressId	string
  deliveryAddressId	string
  lines	object[]
  subtotal	number
  discountTotal	number
  taxTotal	number
  total	number
  invoicedTotal	number
  paidTotal	number
  creditedTotal	number
  source	object
  derived	object[]
  origin	string	API, MANUAL, ODOO or POS.
  externalId	string
  clearance	object
  eInvoice	object
  createdAt	date
  updatedAt	date

• 400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).

  ExampleCopy

  {
    "error": "Lines: at least one line is required.",
    "code": "REQUEST_INVALID"
  }

• 401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).

  ExampleCopy

  {
    "error": "That API key is not valid, or it was revoked.",
    "code": "API_KEY_INVALID"
  }

• 403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).

  ExampleCopy

  {
    "error": "This key's scopes do not include sales.approve.",
    "code": "ROLE_TOO_LOW"
  }

• 404Not found: another type under this route, or another company's (NOT_FOUND).

  ExampleCopy

  {
    "error": "Not found.",
    "code": "NOT_FOUND"
  }

• 409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

  ExampleCopy

  {
    "error": "That externalId is already used by another record of this company.",
    "code": "EXTERNAL_ID_TAKEN"
  }

• 429Too many requests: wait retryAfter seconds (RATE_LIMITED).

  ExampleCopy

  {
    "error": "Too many requests. Wait a little and try again.",
    "code": "RATE_LIMITED"
  }

Confirm into a sales order

POST/quotations/{id}/confirm

Needs

sales.write

Scopes

sales:write

Confirms the quotation into exactly one sales order and answers the order. Confirmed already: alreadyDone with that order. Costs no credit.

Parameters

Code samples

curl -sS -X POST "https://app.kwn.tax/api/v1/quotations/<id>/confirm" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

• 200OK

  Field	Type	Description
  alreadyDone	boolean	True when the document was already where the action takes it; nothing changed.
  document	object

• 400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).

  ExampleCopy

  {
    "error": "Lines: at least one line is required.",
    "code": "REQUEST_INVALID"
  }

• 401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).

  ExampleCopy

  {
    "error": "That API key is not valid, or it was revoked.",
    "code": "API_KEY_INVALID"
  }

• 403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).

  ExampleCopy

  {
    "error": "This key's scopes do not include sales.approve.",
    "code": "ROLE_TOO_LOW"
  }

• 404Not found: another type under this route, or another company's (NOT_FOUND).

  ExampleCopy

  {
    "error": "Not found.",
    "code": "NOT_FOUND"
  }

• 409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

  ExampleCopy

  {
    "error": "That externalId is already used by another record of this company.",
    "code": "EXTERNAL_ID_TAKEN"
  }

• 429Too many requests: wait retryAfter seconds (RATE_LIMITED).

  ExampleCopy

  {
    "error": "Too many requests. Wait a little and try again.",
    "code": "RATE_LIMITED"
  }

Cancel a quotation

POST/quotations/{id}/cancel

Needs

sales.write

Scopes

sales:write

Cancelled already: alreadyDone.

Parameters

Code samples

curl -sS -X POST "https://app.kwn.tax/api/v1/quotations/<id>/cancel" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

• 200OK

  Field	Type	Description
  alreadyDone	boolean	True when the document was already where the action takes it; nothing changed.
  document	object

• 400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).

  ExampleCopy

  {
    "error": "Lines: at least one line is required.",
    "code": "REQUEST_INVALID"
  }

• 401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).

  ExampleCopy

  {
    "error": "That API key is not valid, or it was revoked.",
    "code": "API_KEY_INVALID"
  }

• 403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).

  ExampleCopy

  {
    "error": "This key's scopes do not include sales.approve.",
    "code": "ROLE_TOO_LOW"
  }

• 404Not found: another type under this route, or another company's (NOT_FOUND).

  ExampleCopy

  {
    "error": "Not found.",
    "code": "NOT_FOUND"
  }

• 409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

  ExampleCopy

  {
    "error": "That externalId is already used by another record of this company.",
    "code": "EXTERNAL_ID_TAKEN"
  }

• 429Too many requests: wait retryAfter seconds (RATE_LIMITED).

  ExampleCopy

  {
    "error": "Too many requests. Wait a little and try again.",
    "code": "RATE_LIMITED"
  }

Print

GET/quotations/{id}/pdf

Needs

sales.read

Scopes

sales:read

The printed document as the app prints it, in English or Arabic (?lang=ar). Counted against the apikey-heavy budget.

Parameters

Code samples

curl -sS -X GET "https://app.kwn.tax/api/v1/quotations/<id>/pdf" \
  -H "X-Api-Key: $KWN_API_KEY"

Responses

• 200OK
• 400Refused: the request or a business rule. The code says which (REQUEST_INVALID, RULE_REFUSED, …).

  ExampleCopy

  {
    "error": "Lines: at least one line is required.",
    "code": "REQUEST_INVALID"
  }

• 401No key, a key that is not ours, or one revoked (API_KEY_INVALID); a merchant not active (MERCHANT_INACTIVE).

  ExampleCopy

  {
    "error": "That API key is not valid, or it was revoked.",
    "code": "API_KEY_INVALID"
  }

• 403The key's scopes do not carry the capability (APP_NOT_GRANTED, ROLE_TOO_LOW), or the plan lacks the app (APP_LOCKED).

  ExampleCopy

  {
    "error": "This key's scopes do not include sales.approve.",
    "code": "ROLE_TOO_LOW"
  }

• 404Not found: another type under this route, or another company's (NOT_FOUND).

  ExampleCopy

  {
    "error": "Not found.",
    "code": "NOT_FOUND"
  }

• 409A conflict: an externalId taken, or a change that could not be saved (EXTERNAL_ID_TAKEN, CONFLICT).

  ExampleCopy

  {
    "error": "That externalId is already used by another record of this company.",
    "code": "EXTERNAL_ID_TAKEN"
  }

• 429Too many requests: wait retryAfter seconds (RATE_LIMITED).

  ExampleCopy

  {
    "error": "Too many requests. Wait a little and try again.",
    "code": "RATE_LIMITED"
  }