DIdigitax
Reverse Invoices

Add reverse credit note with item bar codes

Changed on

Creates a reverse credit note for an existing reverse invoice using item barcodes to identify the items being credited.

post/reverse-credit-notes-with-barcode

Request

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

Request body

return_datestring required

The date of the return (YYYY-MM-DD). Future dates are rejected.

sale_idstring required

The DigiTax ID of the original reverse invoice.

callback_urlstring

Optional URL where DigiTax sends an HTTP POST callback with event sale.sync when the reverse credit note's eTIMS synchronization succeeds or fails. See Callback URLs for the payload. Must use HTTP or HTTPS, include a host, and have no username or password. Localhost and private IP addresses are not allowed.

invoice_detailsstring

Additional details for the invoice associated with the credit note.

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.

Example request

{
  "return_date": "2026-07-14",
  "sale_id": "sale_01HC3J1VVVM05YCTS61G7V3KC6",
  "callback_url": "https://example.com/callback",
  "invoice_details": "General Invoice Details",
  "trader_invoice_number": "12345678901",
  "items": [
    {
      "item_bar_code": "HC3J1VVVM05YCTS61G7V3KC6",
      "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