DIdigitax
Reverse Invoices

Add reverse invoice with item information

Changed on

Creates an invoice on behalf of the supplier using item details supplied directly in the request. The buyer creates regular reverse invoices; a third party creates third-party reverse invoices. The type depends on the supplier's reverse invoicing configuration. See Reverse Invoicing for the process and supplier consent requirements.

post/reverse-invoices-with-items

Request

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

Request body

supplier_idstring required

The DigiTax ID of the supplier for the reverse invoice.

sale_datestring required

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

customer_tinstring

The tax identification number of the customer.

customer_namestring

The customer's name.

customer_phonestring

The customer's phone number.

customer_emailstring

The customer's email address.

payment_type_codestring

The code identifying the payment type.

invoice_detailsstring

Additional details associated with the invoice.

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.

callback_urlstring

Optional URL where DigiTax sends an HTTP POST callback with event sale.sync when the reverse invoice's eTIMS synchronization succeeds or fails. See Callback URLs for the payload. Must use HTTP(S), include a host, and contain no credentials. Literal localhost and private IP addresses are rejected.

Example request

{
  "supplier_id": "supplier_01JS16JDB2B5ESZ8HWJ3CBYP5Y",
  "sale_date": "2026-07-14",
  "customer_tin": "P123456789Y",
  "customer_name": "John Doe",
  "customer_phone": "+254714267891",
  "customer_email": "john@doe.com",
  "payment_type_code": "07",
  "invoice_details": "Invoice Details",
  "trader_invoice_number": "12345678901",
  "callback_url": "https://example.com/callback",
  "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"
    }
  ]
}

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

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status