eTIMS

Prerequisites

Before you configure the integration, confirm that:

• The kenya_compliance_via_slade app is installed and bench migrate has been run on your site.
• You have your KRA registration details: Tax Payer's PIN (TIN) and Branch ID.
• You have received your Slade360 Advantage API credentials: Server URL, Auth Server URL, Client ID, Client Secret, Auth Username, Auth Password, and the Slade360 Organisation, Branch, and Department UUIDs for your entity.
• Background workers are running on your iVendNext server — all eTIMS submissions process asynchronously.
• You hold the System Manager role in iVendNext Desk.

How to Create

1. Open the eTIMS Workspace or search for iVendNext KRA eTIMS Settings in the Desk search bar.
2. Click New.
3. Select the Company this record applies to. Each company requires its own settings record.
4. Enter your Tax Payer's PIN (TIN) and select the Branch Id — both are required by KRA to associate submissions with the correct taxpayer.
5. Set Environment to Sandbox for testing or Production for live submissions. Check Sandbox Environment if testing; this routes all calls to Slade360's test endpoint, keeping test data separate from live KRA records.
6. Enter the Server URL and Auth Server URL from Slade360 (these differ between sandbox and production). Then enter your Client ID, Client Secret, Auth Username, and Auth Password. The secret and password fields are encrypted at rest.
7. In the Organisation Mapping table, add at least one row with the Slade360 Organisation, Branch, and Department UUIDs for your entity.
8. Click Get New Token to verify connectivity. If credentials are correct, the Access Token field populates automatically.
9. Enable the auto-submission toggles you need: Sales Auto Submission Enabled, Purchase Auto Submission Enabled, Stock Auto Submission Enabled.
10. Optionally set Max Sales Submission Attempts, Max Purchase Submission Attempts, and Max Stock Submission Attempts to control how many background retries iVendNext performs before flagging a transaction as failed.
11. Check Is Active and click Save.

Features

Automatic POS Invoice Submission

When Sales Auto Submission Enabled is active, every POS Invoice submitted in iVendNext is automatically queued for eTIMS submission in the background. iVendNext calculates the tax breakdown per line item and sends the invoice data to KRA via Slade360. The cashier completes the transaction as normal — no extra steps are required.

On a successful submission, the custom_successfully_submitted field is set to 1 and the custom_qr_code field is populated with the KRA-issued QR code, which prints on the customer receipt as legal proof of compliance.

If submission fails, an eTIMS Actions button group appears on the invoice form. Use Send Invoice to manually re-trigger submission for that invoice. If the QR code is missing after a successful submission, Sync Invoice Details retrieves it from Slade360 without resubmitting. Verify Submission and Resend if Incorrect cross-checks the iVendNext record against Slade360 and corrects discrepancies — useful during audits. When you have multiple active settings records, clicking any of these buttons first shows a settings-selection dialog.

Invoices are automatically excluded from submission when is_opening is set to Yes (opening-balance entries) or when prevent_etims_submission is enabled on the invoice.

Credit Notes and Return Invoice Handling

When a cashier processes a return, iVendNext creates a return POS Invoice and the integration submits it to KRA as a CreditNoteSaveReq — not a new sales invoice — referencing the original Slade360 record so the tax reversal is correctly recorded. If the original invoice was never submitted to eTIMS, the return submission is blocked and iVendNext displays a warning.

Submitted invoices cannot be cancelled directly. If you attempt to cancel an invoice with custom_successfully_submitted = 1, iVendNext blocks the action and directs you to raise a Credit Note instead. This protects the audit trail in both iVendNext and KRA's system.

Item Registration

Every item must be registered in Slade360 before it can appear on a KRA-compliant invoice. iVendNext triggers registration automatically each time an Item is saved, but only when all seven required eTIMS fields are complete: Item Classification (the KRA Harmonised System commodity code), Product Type, Item Type, Taxation Type (KRA categories A through E for different VAT treatments), Packaging Unit, Unit of Quantity, and Country of Origin. If any field is missing, iVendNext throws a validation error listing the specific fields to complete. The item cannot be saved until all fields are present.

Once registered, the custom_item_registered flag is set and the item is locked against deletion. To exclude an item from eTIMS entirely — for example, an internal service item — check Prevent eTIMS Registration on the item record.

To register your existing catalogue before going live, open your settings record and click Register All Items to queue all unregistered items in one batch.

Customer, Supplier, and Payment Mode Sync

iVendNext syncs Customer and Supplier records to Slade360 automatically on first save. When require_tax_id is active on a customer, saving without a Tax ID throws a validation error to prevent incomplete records from reaching the KRA partner registry.

For partners that existed before the integration was configured, use Submit All Customers and Submit All Suppliers in the settings record to sync them in bulk — run these as part of your go-live checklist. For payment methods, open each Mode of Payment record and click Submit to eTims to map it to the corresponding Slade360 account.

Stock Movement Reporting

When Stock Auto Submission Enabled is active, inventory movements — goods receipt notes, stock reconciliations, dispatch notes — are automatically reported to KRA through a three-step background flow: iVendNext creates a stock movement in Slade360, adds line-item detail, then transitions it to PROCESSED. Internal Material Transfer entries are excluded and not reported to KRA. The Max Stock Submission Attempts setting controls how many retries occur before a failed entry is flagged for manual intervention.

Bulk Operations and Reporting

From the POS Invoice list view, you can apply Bulk Submit to eTims or Verify and Resend across multiple unsubmitted invoices at once — the fastest recovery path after a connectivity outage.

Five reports are available in the eTIMS Workspace: Document Submission Status (submitted, pending, and failed counts by transaction type), Integration Requests (full API call log), Integration Request Time Analysis, Document Submission Time Analysis, and Failed Integration Requests Analysis. Use Document Submission Status as your primary compliance dashboard before KRA filing deadlines.