How iVendNext Handles KRA Invoice Submission

For a retail business operating in Kenya, every POS Invoice is simultaneously a sales transaction and a tax event. Kenya Revenue Authority requires the transaction data to reach eTIMS before — or at the moment — the receipt is issued to the customer. iVendNext's eTIMS integration fulfills this obligation automatically, without adding any steps to the cashier's workflow.

The moment a cashier submits a POS Invoice in iVendNext, a background process takes over. iVendNext calculates the tax breakdown for each line item, builds the submission payload in the format Slade360 expects, and enqueues the API call in iVendNext's background job system. The cashier sees the invoice move to submitted status and can continue to the next transaction. The eTIMS submission happens asynchronously — it does not hold up the POS screen.

This asynchronous design ensures that KRA reporting never slows down the point of sale.

What Happens During Submission

When the background job runs, iVendNext calls the Slade360 API endpoint for sales invoices (SalesInvoiceSaveReq). The payload includes the invoice header (date, customer, branch, payment mode), each line item with its eTIMS-specific tax classification, and the tax amounts calculated by iVendNext.

On a successful response from Slade360, two things happen on the POS Invoice record in iVendNext Desk. The custom_successfully_submitted field is set to 1 — this is the definitive indicator that KRA has received and accepted the invoice. The custom_qr_code field is populated with the KRA-issued QR code image. This QR code is what makes the receipt legally compliant: it encodes the KRA's reference for the transaction and can be scanned to verify the invoice in KRA's system.

Finance Managers can filter the POS Invoice list by submission status to immediately identify any invoices where custom_successfully_submitted remains 0. These are invoices that either failed to submit or have not yet been processed. The list view also supports bulk submission and resend actions, which are covered in detail in the Bulk Operations article.

The eTIMS Actions Menu

Once a POS Invoice has been submitted in iVendNext, a button group labelled eTIMS Actions becomes visible on the invoice form. This menu adapts based on the current submission state of the invoice.

If custom_successfully_submitted is 0, the Send Invoice button appears — clicking it manually triggers submission for that invoice, the primary recovery tool for individual failures caused by transient network errors.

If the invoice was submitted but custom_qr_code is empty, the Sync Invoice Details button appears. This retrieves the invoice details from Slade360 and repopulates the QR code field without resubmitting to KRA.

The Verify Submission and Resend if Incorrect button is always visible on submitted invoices. It cross-checks the iVendNext submission status against the actual record in Slade360 and corrects any discrepancy — useful in audit scenarios.

When a company has multiple active eTIMS settings records, clicking any eTIMS Actions button first presents a settings-selection dialog so the user can choose which branch configuration to use.

Invoices That Are Excluded from Submission

Not every POS Invoice in iVendNext should be submitted to eTIMS. Opening-balance invoices created during system setup, for example, represent historical stock positions rather than actual sales and should not generate KRA records.

iVendNext handles this through two mechanisms. The is_opening flag on POS Invoices marks opening-entry documents; the integration automatically skips any invoice where this flag is set to Yes. For other scenarios where a specific invoice should be excluded — such as internal test transactions or corrections made during initial data migration — the prevent_etims_submission field can be set on the individual invoice. When this field is enabled, the submission hook exits silently without attempting to contact Slade360.

These exclusion rules ensure that the KRA submission log reflects genuine trading activity. Sending irrelevant transactions to eTIMS would distort the company's tax records and potentially trigger unnecessary KRA enquiries.

Return Invoices and Credit Notes

When a customer returns goods and the cashier processes a return at the POS, iVendNext creates a return POS Invoice — a document with is_return set to True. This return must also be reported to KRA, but not as a new sale. KRA requires it to be submitted as a credit note that references the original invoice, so that the tax reversal is correctly recorded against the initial transaction.

iVendNext handles this automatically. When a return POS Invoice is submitted, the integration identifies it as a return, retrieves the original invoice's Slade360 reference, and submits a CreditNoteSaveReq to Slade360 in place of the standard sales invoice call. KRA receives the reversal linked to the correct original transaction, maintaining an accurate running record of the business's tax position.

There is one important prerequisite: the original invoice must have been successfully submitted to eTIMS before a credit note can be raised against it. If the original invoice's custom_successfully_submitted flag is 0, the system will display a warning and will not proceed with the credit note submission. This rule exists because a credit note referencing an invoice that does not exist in KRA's system would be rejected. In practice, the Finance Manager should ensure the original invoice is submitted successfully — using the Send Invoice button if necessary — before processing the return.

Why Submitted Invoices Cannot Be Cancelled

A common point of confusion for teams transitioning from other POS systems is that iVendNext will not allow a POS Invoice to be cancelled once it has been successfully submitted to eTIMS.

This restriction is not arbitrary. Once KRA has acknowledged an invoice, that transaction exists as a tax record in the revenue authority's system. Cancelling the iVendNext document would create an irreconcilable discrepancy: KRA would hold a record of a sale that iVendNext no longer shows. This kind of mismatch is exactly what KRA compliance audits look for, and it exposes the business to penalties.

When a user attempts to cancel a submitted POS Invoice, iVendNext blocks the action and displays a clear message explaining that the invoice has already been submitted to eTIMS and directing the user to create a Credit Note instead. The Credit Note path — a return POS Invoice — is the correct and legally compliant way to reverse a submitted sale, because it creates a corresponding record in KRA's system that cancels out the original.