eTIMS Credit Notes API

Submit credit notes to KRA for full or partial reversals of previously submitted sales. Credit notes generate reversal receipts and adjust tax records.

Table of Contents

1. Overview
2. Submit Credit Note
3. Express Credit Note (Full Reversal)
4. List Credit Notes
5. Status Codes

Overview

Required Scopes

Endpoint Summary

How Credit Notes Work in eTIMS

A credit note in eTIMS is a sale transaction with rcptTyCd = "R" (Refund/Return). It references the original invoice and creates a negative entry to offset the original sale.

Original Sale (rcptTyCd: "S")  -->  Credit Note (rcptTyCd: "R")
  Total: +30,000 KES                 Total: -30,000 KES
  Tax:    +4,138 KES                 Tax:    -4,138 KES

Submit Credit Note

Submit a credit note against a specific original sale. Supports partial credit notes (returning some items or partial quantities).

Endpoint: POST /api/etims/credit-notes/submit

Required Scope: etims:write

Request Body:

Item Fields

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/credit-notes/submit \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_receipt_number": "INV-2026-001",
    "reason": "Defective item returned by customer",
    "items": [
      {
        "item_seq": 1,
        "item_code": "ITEM001",
        "item_name": "Office Chair",
        "quantity": 1,
        "unit_price": 15000.00,
        "tax_type": "B"
      }
    ],
    "remark": "1 of 2 chairs returned - defective armrest"
  }'

Response:

{
  "success": true,
  "data": {
    "credit_note_id": 45,
    "original_sale_id": 789,
    "original_receipt_number": "INV-2026-001",
    "credit_note_receipt": "INV-2026-001-CN1",
    "cu_invoice_number": "CU2026001-00003",
    "return_date": "2026-03-29",
    "reason": "Defective item returned by customer",
    "total_items": 1,
    "total_taxable_amount": 12931.03,
    "total_tax_amount": 2068.97,
    "total_amount": 15000.00,
    "tax_breakdown": {
      "B": {"taxable": 12931.03, "tax": 2068.97, "rate": 16}
    },
    "status": "submitted",
    "submitted_at": "2026-03-29T16:20:00Z"
  },
  "message": "Credit note submitted successfully"
}

Express Credit Note

Submit an express credit note that performs a full reversal of the original sale. All items and amounts are reversed automatically -- no need to specify individual items.

Endpoint: POST /api/etims/credit-notes/express

Required Scope: etims:write

Request Body:

Request:

curl -X POST \
  https://yourtenant.salami.dgl.co.ke/api/etims/credit-notes/express \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "original_receipt_number": "INV-2026-002",
    "reason": "Order cancelled by customer before delivery"
  }'

Response:

{
  "success": true,
  "data": {
    "credit_note_id": 46,
    "original_sale_id": 790,
    "original_receipt_number": "INV-2026-002",
    "credit_note_receipt": "INV-2026-002-CN",
    "cu_invoice_number": "CU2026001-00004",
    "return_date": "2026-03-29",
    "reason": "Order cancelled by customer before delivery",
    "total_items": 1,
    "total_taxable_amount": 15086.21,
    "total_tax_amount": 2413.79,
    "total_amount": 17500.00,
    "reversal_type": "full",
    "status": "submitted",
    "submitted_at": "2026-03-29T16:25:00Z"
  },
  "message": "Express credit note (full reversal) submitted successfully"
}

List Credit Notes

Retrieve all credit notes.

Endpoint: GET /api/etims/credit-notes

Required Scope: etims:read

Query Parameters:

Request:

curl -X GET \
  'https://yourtenant.salami.dgl.co.ke/api/etims/credit-notes?start_date=2026-03-01' \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

Response:

{
  "success": true,
  "data": [
    {
      "id": 45,
      "original_receipt_number": "INV-2026-001",
      "credit_note_receipt": "INV-2026-001-CN1",
      "reason": "Defective item returned by customer",
      "total_amount": 15000.00,
      "total_tax_amount": 2068.97,
      "status": "submitted",
      "submitted_at": "2026-03-29T16:20:00Z"
    },
    {
      "id": 46,
      "original_receipt_number": "INV-2026-002",
      "credit_note_receipt": "INV-2026-002-CN",
      "reason": "Order cancelled by customer before delivery",
      "total_amount": 17500.00,
      "total_tax_amount": 2413.79,
      "status": "submitted",
      "submitted_at": "2026-03-29T16:25:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "per_page": 50,
    "current_page": 1,
    "last_page": 1
  }
}

Status Codes

Best Practices

1. Always reference the original sale -- Credit notes must link to a valid original receipt
2. Partial vs full -- Use submit for partial returns, express for full reversals
3. Matching tax types -- Returned items must use the same tax type as the original
4. Amounts cannot exceed original -- The credit note total cannot exceed the original sale total
5. Submit promptly -- File credit notes as soon as the return occurs
6. Keep documentation -- Record the reason for every credit note

Related Documentation

• eTIMS Sales -- Submit original sales
• eTIMS Reverse Invoices -- Supplier-side invoice reversals
• eTIMS Codes -- Receipt type codes

Back to: eTIMS Sales | eTIMS Purchases