Add Sale with Item Information

POST/api/v1/sales-with-items

Submit a sales invoice and optionally auto-register each line item with Kenya Revenue Authority in the same request. When autoRegisterItems is true, each line item containing itemClsCd is registered via POST /saveItem before the sale is submitted. Item registration failures are non-fatal, the sale proceeds even if an item was already registered.

Requires x-api-key

http://localhost:8100/api/v1/sales-with-items

Headers

Field	Type	Required	Description
x-api-key	string	Required	Your Ushuru API key.
Content-Type	string	Required	application/json

Top-Level Body Fields

Field	Type	Required	Description
transaction	object	Required	Transaction header, same fields as POST {{API_PATH}}/sales.
lineItems	array	Required	Line items. Each may include itemClsCd for auto-registration.
receipt	object	Optional	Receipt metadata. Defaults to empty object if omitted.
autoRegisterItems	boolean	Optional	When true, registers each line item with Kenya Revenue Authority before submitting. Default: false.

Line Item Fields

Field	Type	Required	Description
itemClsCd	string	Optional	10-digit Kenya Revenue Authority classification code. Required when autoRegisterItems is true.
itemCd	string	Required	Your Kenya Revenue Authority item code (e.g. SV0000000Z001).
itemTyCd	string	Optional	Item type, 1=Raw, 2=Finished, 3=Service. Defaults to '3'.
itemNm	string	Required	Item name.
orgnNatCd	string	Optional	Origin country code. Defaults to 'KE'.
pkgUnitCd	string	Optional	Packaging unit code.
qtyUnitCd	string	Required	Quantity unit code.
taxTyCd	string	Required	Tax type: A=Exempt, B=16% VAT, C=0%, D=Non-VAT, E=8%.
prc	number	Required	Unit price (also used as dftPrc when registering the item).
qty	number	Required	Quantity sold.
taxblAmt	number	Required	Taxable amount for this line.
taxAmt	number	Required	Tax amount for this line.
totAmt	number	Required	Total amount inclusive of tax.

Request

{
  "autoRegisterItems": true,
  "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,
    "regrId": "USR01",
    "regrNm": "Admin",
    "modrId": "USR01",
    "modrNm": "Admin"
  },
  "lineItems": [
    {
      "itemClsCd": "5020230000",
      "itemCd": "SV0000000Z001",
      "itemTyCd": "3",
      "itemNm": "Monthly SaaS Subscription",
      "orgnNatCd": "KE",
      "pkgUnitCd": "NT",
      "qtyUnitCd": "U",
      "taxTyCd": "B",
      "prc": 5000,
      "qty": 1,
      "dcRt": 0,
      "dcAmt": 0,
      "taxblAmt": 4310.34,
      "taxAmt": 689.66,
      "totAmt": 5000
    }
  ]
}

Response

{
  "success": true,
  "message": "Sale submitted to Kenya Revenue Authority. Print internalData and receiptSignature on receipt.",
  "data": {
    "cisInvcNo": 43,
    "intrlData": "AbCdEfGhIjKlMnOpQrStUvWxYz...",
    "rcptSign": "XxXxXxXxXxXxXxXxXxXxXxXx...",
    "sdcDateTime": "20240115103045",
    "totRcptNo": 43
  }
}

curl -X POST http://localhost:8100/api/v1/sales-with-items \\
  -H "x-api-key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "autoRegisterItems": true,
    "transaction": {
      "invcNo": "INV-2024-001",
      "salesDt": "20240115",
      "pmtTyCd": "09",
      "rcptTyCd": "S",
      "salesSttsCd": "02",
      "totTaxblAmt": 4310.34,
      "totTax": 689.66,
      "totAmt": 5000,
      "regrId": "USR01",
      "regrNm": "Admin",
      "modrId": "USR01",
      "modrNm": "Admin"
    },
    "lineItems": [{
      "itemClsCd": "5020230000",
      "itemCd": "SV0000000Z001",
      "itemNm": "Monthly SaaS Subscription",
      "qtyUnitCd": "U",
      "taxTyCd": "B",
      "prc": 5000,
      "qty": 1,
      "taxblAmt": 4310.34,
      "taxAmt": 689.66,
      "totAmt": 5000
    }]
  }'