DIdigitax
Sales

Add express credit note

Changed on

Add express credit note i.e. a full credit note for a particular sale. This should be used when a credit note has not previously been generated for a sale.

post/credit-notes/express

Request

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

Request body

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.

return_datestring required

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

sale_idstring required

The DigiTax-generated sale ID of the original sale.

callback_urlstring

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

invoice_detailsstring

Additional details associated with the credit note.

credit_note_reasonstring

The reason code for crediting the original sale. Valid values are 01 (Missing Quantity),02 (Missing Data), 03 (Damaged), 04 (Wasted), 05 (Material Shortage), and 06 (Refund).

Example request

{
  "trader_invoice_number": "12345678901",
  "return_date": "2026-07-14",
  "sale_id": "sale_01HC3J1VVVM05YCTS61G7V3KC6",
  "callback_url": "https://example.com/callback",
  "invoice_details": "General Invoice Details",
  "credit_note_reason": "06"
}

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 new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status