Credit Notes

A credit note reverses or adjusts an already-fiscalised invoice - returns, cancellations, and pricing corrections. Unlike an invoice, a credit note is an application: it goes through an approval step before URA issues its FDN.

Flow: original fiscal invoice → apply for credit note → track approval status (/query-credit-notes, /query-credit-note-details) → once approved, retrieve the credit note's FDN and QR code via /invoice-details.
Time limit: a credit note cannot be submitted after the URA-configured maximum number of days from the original invoice date.

POST/apply-for-credit-note

The body wraps the application in a credit_note object. All quantities and amounts must be NEGATIVE - they reverse the original invoice.

A. Credit note against an original invoice

{
    "credit_note": {
        "oriInvoiceId": "1000002", // invoiceId returned for the original invoice
        "oriInvoiceNo": "322000150744", // The original FDN - must exist and match oriInvoiceId
        "reasonCode": "101",
        "reason": "", // Required only when reasonCode = 105
        "applicationTime": "2026-06-01 10:00:00", // yyyy-MM-dd HH:mm:ss
        "invoiceApplyCategoryCode": "101", // 101: creditNote
        "currency": "UGX", // Must match the original invoice currency
        "source": "103", // 103: WebService API
        "remarks": "Customer returned defective goods",
        "sellersReferenceNo": "CN-2026-001",
        "goodsDetails": [
            {
                "item": "Premium Water 500ml", // Same as original invoice
                "itemCode": "SKU-BOTTLE-01", // Same as original invoice
                "qty": "-1", // NEGATIVE - cannot exceed original quantity
                "unitOfMeasure": "101",
                "unitPrice": "100000",
                "total": "-100000", // NEGATIVE - cannot exceed original amount
                "taxRate": "0.18", // Same as original invoice
                "tax": "-15254.24", // NEGATIVE
                "orderNumber": "0",
                "deemedFlag": "2", // Same as original invoice
                "exciseFlag": "2", // Same as original invoice
                "goodsCategoryId": "22011000" // Same as original invoice
            }
        ],
        "taxDetails": [
            {
                "taxCategoryCode": "01",
                "netAmount": "-84745.76", // Negative or 0
                "taxRate": "0.18",
                "taxAmount": "-15254.24", // Negative or 0
                "grossAmount": "-100000.00" // Strictly negative
            }
        ],
        "summary": {
            "netAmount": "-84745.76",
            "taxAmount": "-15254.24",
            "grossAmount": "-100000.00",
            "itemCount": "1",
            "modeCode": "1"
        },
        "buyerDetails": {
            "buyerType": "1",
            "buyerLegalName": "John Doe"
        },
        "basicInformation": {
            "operator": "Jane Kasule",
            "invoiceKind": "1"
        }
    }
}

Response: data contains only { "referenceNo": "..." } - keep it to track the application through approval.

reasonCode:

Code	Meaning
`101`	Return of goods due to expiry or damage, etc.
`102`	Cancellation of the purchase
`103`	Invoice amount wrongly stated due to miscalculation of price, tax, or discounts, etc.
`104`	Partial or complete waive off of the good sale after the invoice is generated and sent to customer
`105`	Others - `reason` is REQUIRED

Excise items on credit notes: carry over the original excise fields (categoryId, categoryName, exciseRate, exciseRule, exciseUnit, exciseCurrency, exciseRateName, pack, stick) unchanged, but exciseTax must be negative.

Attachments (optional): attachmentList: [{ "fileName": "...", "fileType": "png", "fileContent": "BASE64..." }].

Note: Export invoices cannot apply for a credit note (EFRIS error 2050).

B. Credit note without an original FDN

If both oriInvoiceId and oriInvoiceNo are omitted/empty, EFRIS treats the application as a credit note without original FDN (e.g. for invoices issued before EFRIS adoption). All other fields and rules are the same as scenario A.

C. Tracking & approving applications

Endpoint	Purpose
`POST /query-credit-notes`	Paginated list of credit/debit note applications. Optional filters: `referenceNo`, `queryType` (`1` seller / `2` buyer), `approveStatus`, `pageNo`, `pageSize`, etc.
`POST /query-credit-note-details`	Application details. Body: `{ "id": "..." }` (the application `id` from the list response)
`POST /approve-credit-note`	Approve/reject. Body: `{ "referenceNo", "approveStatus", "remark", "taskId" }` - `approveStatus`: `"101"` Approved, `"103"` Rejected
`POST /query-credit-note-application-details`	Query credit note / cancel-debit-note application details. Body: `{ "id": "..." }`

D. Cancelling & voiding

Endpoint	Purpose
`POST /cancel-credit-note`	Cancel an already-approved credit note. Body: `{ "oriInvoiceId", "invoiceNo", "reasonCode", "invoiceApplyCategoryCode", "reason?", "attachmentList?" }` - `invoiceNo` is the FDN of the credit note itself; `reason` required when `reasonCode = "103"`
`POST /void-credit-note`	Void a pending (not yet approved) application. Body: `{ "businessKey", "referenceNo" }` - both come from the `/query-credit-notes` list response
`POST /query-canceled-credit-notes-details`	Query cancellation details. Body: `{ "invoiceNo": "..." }`

What comes next

Once an application is approved, fetch the credit note's own FDN and QR code with POST /invoice-details - the response structure is described in Invoice Response. For debit notes (which increase an invoice's value instead of reducing it), see Fiscal Invoices, scenario H.