Home / EFRIS credit note guide

How to issue an EFRIS credit note through the API

To reverse part or all of a fiscalised invoice or receipt through EFRIS Gateway, submit a credit note application linked to the original document, save the returned application reference, then check its status. A successful submission confirms that the application was received; it does not mean URA has approved or issued the credit note.

This guide is for accountants working with an integrated system and developers using our gateway. It describes the gateway API workflow, rather than the buttons in the URA web portal. Start with the API developer guide if you have not connected your application yet.

1. Retrieve the original fiscal document

Keep the original fiscal document number (FDN), source invoice reference, customer and item details. Use GET /api/efris/invoice/{fdn} to retrieve the document. Check what is still available to credit with GET /api/efris/invoice-remain-details?invoiceNo={fdn}, particularly if an earlier return has already been recorded.

For each returned item, use the item code, unit of measure, unit price and tax treatment from the original sale. Include its excise details where applicable. Changing these details can cause the application to be rejected because it no longer matches the original invoice.

2. Prepare the return or correction

Create a reference for the credit note in your own system and record the reason. For a partial return, include only the quantity being credited. The simple API format accepts positive quantities and amounts; the gateway constructs the credit amounts for submission.

A credit against a tax invoice must state each item's original tax treatment. A credit against a receipt carries no VAT, as the receipt had none. For receipt credits, omit tax_rate or send 0; the gateway refuses VAT charged against a receipt.

3. Submit the credit note application

Send POST https://efrisgateway.com/api/efris/submit-credit-note from your backend with your taxpayer's X-API-Key header and Content-Type: application/json. Keep the key out of browser code. The following illustrative payload credits two units from an invoice; replace the example document and item details with the original sale's values.

{
  "credit_note_number": "CN-EXAMPLE-001",
  "operator": "Example Operator",
  "original_invoice_number": "325043056477",
  "original_fdn": "325043056477",
  "customer_name": "Example Customer Ltd",
  "buyer_type": "1",
  "reason": "Goods returned",
  "reason_code": "101",
  "items": [{
    "item_name": "Bottled water 500ml",
    "item_code": "WTR-500",
    "quantity": 2,
    "unit_price": 1500,
    "tax_rate": 18,
    "unit_of_measure": "101"
  }]
}

The item, unit and tax values above are examples, not defaults for every business. Send the real operator's name, or configure a default operator for the taxpayer account. The full integration guide explains the accepted fields, buyer types and reason codes. Use the Postman collection to prepare requests in your agreed test environment.

4. Track the application before treating it as issued

On a successful submission, store referenceNo alongside your own credit note number. Query GET /api/efris/credit-notes?referenceNo={referenceNo} to track the application. Keep submitted, approved and rejected states distinct in your accounts and operator screens. Use the confirmed fiscal result when recording and printing the issued credit document.

A network timeout leaves the outcome uncertain. Reconcile the application before submitting another request; do not assume that an interrupted response means URA never received it.

Why was the credit note rejected?

• Missing fields: provide the credit note number, original invoice reference, customer name, reason and items. Always send the original FDN for matching.
• Item differs from the original: compare item codes, units, prices, taxes and excise details with the original document. URA error 1464 can indicate this mismatch.
• Incorrect VAT treatment: preserve the original invoice's treatment and do not add VAT to a receipt credit.
• Quantity already credited: check the remaining creditable details and earlier applications before attempting another return.

Read the returned error details, correct the source transaction and reconcile its state before retrying. If you need help, send the document reference and error code through your support channel; never include your API key.

Can this work from our accounting software?

The same workflow can support an integration with QuickBooks, Tally, Sage, Odoo, Zoho Books or custom software. Your connector must pass the original document details and track the application result. Discuss your version and return workflow with us before implementation.

For onboarding and deployment choices, read the business integration guide.

Who you are buying from

Enterprise software, Acounting software, EFRIS integration and tax compliance � Kampala, Uganda.

Registered name

Midway Systems Ltd

Company registration

80040689807095 (URSB, Uganda)

Address

Nabisunsa Close, Kyambogo

Company website

midwayug.com

Email

[email protected]

Phone

+256706090021

Talk to us

Send a message and we will come back to you.

Kyambogo-k4-Nakawa