DIdigitax
Sales

Add sale with item information

Changed on

Creates a sale using item details supplied directly in the request.

post/sales-with-items

Request

  • Base URL
    https://api.digitax.tech/ke/v2
  • Auth
    API key in header X-API-Key

Request body

sale_datestring required

The date of the sale (YYYY-MM-DD). Dates after the current UTC date are rejected.

customer_tinstring

The KRA-approved tax identification number of the customer.

customer_namestring

The customer's name. If only the customer_name is provided and the customer_tin is omitted, a given sale will not have any customer details

customer_idstring

The DigiTax-generated customer ID. If both the customer_id and customer_tin+customer_name are provided, the customer_id is prioritised.

trader_invoice_numberstring required

The invoice reference from your system. It must be unique across sales and credit notes in the business. References from failed transactions can be reused.

receipt_type_codestring

This field is deprecated and will be ignored if provided. The receipt type code is populated automatically based on invoice type

payment_type_codestring required

The code identifying the payment method used for the sale.

invoice_status_codestring required

The invoice status code. Refer to the Invoice Status Codes table for the code values.

callback_urlstring

Optional URL where DigiTax sends an HTTP POST callback with event sale.sync when the sale's eTIMS synchronization succeeds or fails. See Callback URLs for the payload.

invoice_detailsstring

Allows for additional details to be captured in the invoice. This is not transmitted to KRA.

is_tax_exemptboolean

Indicates if the sale is tax-exempt.

Example request

{
  "sale_date": "2026-07-14",
  "customer_tin": "P123456789Y",
  "customer_name": "John Doe",
  "customer_id": "customer_01HC3HTDAXQ50E07CWR2A2CFBD",
  "trader_invoice_number": "12345678901",
  "receipt_type_code": "S",
  "payment_type_code": "07",
  "invoice_status_code": "01",
  "callback_url": "https://example.com/callback",
  "invoice_auth": {
    "type": "REVERSE",
    "issuer": "business_01HC3J1VVVM05YCTS61G7V3KC6"
  },
  "invoice_details": "Invoice Details",
  "items": [
    {
      "item_name": "Item name",
      "item_class_code": "99000000",
      "item_bar_code": "99000001",
      "item_tax_type_code": "D",
      "quantity": 1,
      "unit_price": 3500,
      "total_amount": 3500,
      "taxable_amount": 3500,
      "package_unit_quantity": 1,
      "item_description": "DigiTax Product 01",
      "is_stockable": true
    }
  ]
}

Response

Success

idstring required

The DigiTax ID of the sale.

datestring required

The receipt date (DD/MM/YYYY), as printed on the physical receipt

timestring required

The time shown on the receipt.

trader_invoice_numberstring required

The invoice reference from your system. It must be unique across sales and credit notes in the business. References from failed transactions can be reused.

receipt_type_codestring required

The code identifying the receipt type, such as S for an invoice or R for a credit note.

credit_note_reasonstring

The reason code for the credit note. Values are 01 (Missing Quantity), 02 (Missing Data), 03 (Damaged), 04 (Wasted), 05 (Material Shortage), and 06 (Refund).

sale_detail_urlstring url required

The URL for accessing the sale details.

serial_numberstring required

The receipt serial number issued by KRA.

receipt_numberinteger required

The receipt number associated with the sale.

invoice_numberinteger required

The invoice number associated with the sale.

customer_idstring required

The DigiTax ID of the customer associated with the sale.

customer_namestring required

The name of the customer associated with the sale.

customer_tinstring required

The tax identification number of the customer.

customer_phone_numberstring

The customer's phone number.

customer_emailstring

The customer's email address.

internal_datastring required

The internal data returned for the sale.

receipt_signaturestring required

The signature associated with the receipt.

etims_urlstring url required

The URL for viewing the receipt in the eTIMS.

original_sale_idstring

The DigiTax ID of the original sale.

offline_urlstring url

The URL for accessing the sale receipt offline.

status'PENDING' | 'FAILED' | 'COMPLETED'

status against KRA

kra_response_messagestring

The optional KRA-provided error message. This is only provided if a sale has failed.

Example response

{
  "id": "sale_01HC3HTDAXQ50E07CWR2A2CFBD",
  "date": "14/07/2026",
  "time": "04:16:11 pm",
  "trader_invoice_number": "12345678901",
  "receipt_type_code": "S",
  "credit_note_reason": "06",
  "sale_detail_url": "https://api.digitax.tech/sales/YKSWCIiuvx",
  "serial_number": "KRACU0400000001",
  "receipt_number": 38,
  "invoice_number": 38,
  "customer_id": "customer_01HC3HTDAXQ50E07CWR2A2CFBD",
  "customer_name": "John Doe",
  "customer_tin": "P123456789P",
  "customer_phone_number": "+254112685368",
  "customer_email": "info@namiri.tech",
  "internal_data": "PB3ZSZP3RZR3AUPYBYLUTFJDIA",
  "receipt_signature": "3JYZVPTPMYBGHG4A",
  "etims_url": "https://etims.kra.go.ke/common/link/etims/receipt/indexEtimsReceptData?{P053100692D+00+3JYZVPTPMYBGHG4A}",
  "original_sale_id": "sale_01HC3HTDAXQ50E07CWR2A2CFBD",
  "offline_url": "https://receipt.dg.tax/r/business_01JGXVVP4Z3MWQBQ3XSCJ3S4JF/SAL25-204-145657411-MHARTQ",
  "status": "completed",
  "sales_tax_summary": {
    "taxable_amount_b": 517.24,
    "tax_rate_b": 16,
    "tax_rate_e": 8,
    "catering_levy_rate": 2,
    "tax_amount_b": 82.76
  },
  "item_list": [
    {
      "id": "saleitem_01HC3J1VVVM05YCTS61G7V3KC6",
      "quantity": 1,
      "unit_price": 600,
      "total_amount": 600,
      "taxable_amount": 517.24,
      "tax_amount": 82.76,
      "tax_rate": 16,
      "tax_type_code": "B",
      "etims_item_code": "KE3NTU12345678",
      "item_id": "item_01HC3J1VVVM05YCTS61G7V3KC6"
    }
  ]
}

Changes

  • 6a186b8718c5Revision changes
    • info

      request property deprecated

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status