Add a Sale

POST/api/v1/sales

Submit a sales invoice to Kenya Revenue Authority. This is the core compliance endpoint, every sale your business makes must be submitted here before or immediately after issuing a receipt to the buyer. Kenya Revenue Authority returns a receipt signature and internal data that must appear on every printed or digital receipt.

Requires x-api-key

http://localhost:8100/api/v1/sales

Transaction Fields

Field	Type	Required	Description
invcNo	string	Required	Your internal invoice/receipt number. Must be unique per taxpayer.
orgInvcNo	string	Optional	Original invoice number, required only for credit notes and copies.
salesDt	string	Required	Sale date in YYYYMMDD format (e.g. 20240115).
stockRlsDt	string	Optional	Stock release date in YYYYMMDDHHmmss format.
custTin	string	Optional	11-character Kenya Revenue Authority PIN of the buyer. Required for B2B sales.
custNm	string	Optional	Buyer name. Required if custTin is provided.
pmtTyCd	string	Required	Payment method code. See Payment Method Codes section.
rcptTyCd	string	Required	Receipt type: S=Sale, R=Return, T=Training, C=Copy.
salesSttsCd	string	Required	Sales status code. See Sales Status Codes section.
cfmDt	string	Optional	Confirmation date in YYYYMMDDHHmmss format.
currency	string	Required	Transaction currency (e.g. KES, USD).
exchangeRate	number	Required	Exchange rate to KES. Use 1 for KES transactions.
destnCountryCd	string	Required	Destination country code (e.g. KE for domestic).
prchrAcptcYn	string	Optional	Purchaser acceptance: Y or N.
remark	string	Optional	Optional remark for this transaction.
totTaxblAmt	number	Required	Total taxable amount (exclusive of VAT).
totTax	number	Required	Total VAT amount.
totAmt	number	Required	Total invoice amount inclusive of VAT (totTaxblAmt + totTax).

Line Item Fields

Field	Type	Required	Description
itemSeq	number	Optional	Line item sequence number. Auto-assigned if omitted.
itemCd	string	Required	Item code from your registered items (e.g. SV0000000Z001).
itemClsCd	string	Optional	Item class code: SV=Service, GD=Goods. Inferred from itemCd if omitted.
itemNm	string	Required	Item name as it appears on the receipt.
bcd	string	Optional	Barcode for goods items.
pkgUnitCd	string	Optional	Packaging unit code.
pkg	number	Optional	Package count.
qtyUnitCd	string	Required	Quantity unit code (e.g. U=Unit, KG=Kilogram).
qty	number	Required	Quantity sold.
prc	number	Optional	Unit price before discount.
splyAmt	number	Optional	Supply amount (qty x prc).
dcRt	number	Optional	Discount rate as a percentage (0-100).
dcAmt	number	Optional	Discount amount in KES.
taxTyCd	string	Required	Tax type: A=Exempt, B=16% VAT, C=0% VAT, D=Non-VAT.
taxblAmt	number	Required	Taxable amount for this line (exclusive of VAT). For type B: totAmt / 1.16.
taxAmt	number	Required	VAT amount for this line. For type B: taxblAmt * 0.16.
totAmt	number	Required	Total amount for this line inclusive of VAT.
itemExpiryDt	string	Optional	Expiry date for perishable goods in YYYYMMDD format.

Payment Method Codes

Receipt Type Codes

Sales Status Codes

Important

Print on Every Receipt

Request

{
  "transaction": {
    "invcNo": "INV-2024-001",
    "salesDt": "20240115",
    "custTin": "A000000000Z",
    "custNm": "BUYER COMPANY LTD",
    "pmtTyCd": "09",
    "rcptTyCd": "S",
    "salesSttsCd": "02",
    "currency": "KES",
    "exchangeRate": 1,
    "destnCountryCd": "KE",
    "totTaxblAmt": 4310.34,
    "totTax": 689.66,
    "totAmt": 5000
  },
  "items": [
    {
      "itemCd": "SV0000000Z001",
      "itemNm": "Monthly SaaS Subscription",
      "qtyUnitCd": "U",
      "qty": 1,
      "prc": 5000,
      "splyAmt": 5000,
      "dcRt": 0,
      "dcAmt": 0,
      "taxTyCd": "B",
      "taxblAmt": 4310.34,
      "taxAmt": 689.66,
      "totAmt": 5000
    }
  ]
}

Response

{
  "resultCd": "000",
  "resultMsg": "Sales invoice submitted successfully",
  "data": {
    "cisInvcNo": 42,
    "intrlData": "AbCdEfGhIjKlMnOpQrStUvWxYz...",
    "rcptSign": "XxXxXxXxXxXxXxXxXxXxXxXx...",
    "sdcDateTime": "20240115103045",
    "totRcptNo": 42,
    "vsdcRcptPbctDate": "20240115",
    "resultDt": "20240115103045"
  }
}

curl -X POST http://localhost:8100/api/v1/sales \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "transaction": {
      "invcNo": "INV-2024-001",
      "salesDt": "20240115",
      "pmtTyCd": "09",
      "rcptTyCd": "S",
      "salesSttsCd": "02",
      "currency": "KES",
      "exchangeRate": 1,
      "destnCountryCd": "KE",
      "totTaxblAmt": 4310.34,
      "totTax": 689.66,
      "totAmt": 5000
    },
    "items": [
      {
        "itemCd": "SV0000000Z001",
        "itemNm": "Monthly SaaS Subscription",
        "qtyUnitCd": "U",
        "qty": 1,
        "prc": 5000,
        "splyAmt": 5000,
        "dcRt": 0,
        "dcAmt": 0,
        "taxTyCd": "B",
        "taxblAmt": 4310.34,
        "taxAmt": 689.66,
        "totAmt": 5000
      }
    ]
  }'