> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tax and eTIMS

> Submit invoices to KRA through DigiTax, manage tax classes, read certified receipts, and resolve failed submissions.

**Finance → Accounting → Tax → `/tax`** · Provider mappings → `/provider-mappings`

Kenyan tax compliance runs through **eTIMS**, the Revenue Authority's electronic tax invoice
system. Nyumba Zetu submits invoices to eTIMS through the **DigiTax** integration and stores the
certified result on the invoice.

## How tax works on the platform

<Note>
  **Tax is exclusive, everywhere.** Tax is applied on top of the line amount: a KES 10,000 line at
  16% bills KES 11,600. Inclusive tax is deliberately not supported, so no invoice on the platform
  can be ambiguous about whether tax is inside or outside the figure.
</Note>

The tax applied to a line comes from its **service type**, which carries a **tax class**. The
platform default is **class D (Non-VAT)**; VAT-rated items are mapped explicitly. See
[Chart of accounts](/guides/chart-of-accounts).

## Setup

Tax submission requires a connection per business, configured under the integration setup:

| Setting                                  | Purpose                                                   |
| ---------------------------------------- | --------------------------------------------------------- |
| **Connection**                           | The provider connection for a branch or business.         |
| **API key reference / secret reference** | Credentials, held per business rather than platform-wide. |
| **External tenant / branch / device ID** | Identifiers the provider uses for your registration.      |
| **Auth type**                            | How the connection authenticates.                         |
| **Mode**                                 | Which environment the connection targets.                 |

<Warning>
  Credentials are held **per business**. A connection copied from another entity submits that
  entity's invoices under your registration. Set up each business's connection explicitly.
</Warning>

Before submitting real invoices, the item catalogue must be synchronised so that every service
type you bill exists on the provider side.

## Submitting an invoice

<Steps>
  <Step title="Issue the invoice">
    Only issued invoices are submitted.
  </Step>

  <Step title="Send to eTIMS">
    Use the send action on the invoice, or the eTIMS Integration tab. A confirmation dialog states
    what will be submitted.
  </Step>

  <Step title="Watch the status">
    The invoice's eTIMS tab shows the submission status with live updates and an audit trail of
    every attempt.
  </Step>

  <Step title="Read the certified receipt">
    On acceptance the invoice shows **KRA eTIMS Certified** with the QR code, receipt details and
    fiscal identifiers, rendered inline on the invoice.
  </Step>
</Steps>

### Submission statuses

Submissions move through queued → submitted → accepted or failed, with the attempt count and the
reason on failure. The eTIMS tab shows **why it failed** rather than a bare error code.

## Provider mappings

**`/provider-mappings`** is the cross-invoice view of integration state: every submission, its
status, provider, document type, correlation and idempotency keys, attempts, and the failure
reason.

From here you can:

* filter by provider and status to find everything that failed;
* **retry** failed submissions, with background processing hints so you know a retry is in flight;
* drill into an individual mapping's timeline and payload.

A per-invoice mappings tab gives the same detail for one document.

## Available operations

The integration supports the operations eTIMS exposes, including:

| Operation                                                        | Purpose                                       |
| ---------------------------------------------------------------- | --------------------------------------------- |
| **Submit Invoice** / **Verify Invoice** / **Get Invoice Status** | The core submission cycle.                    |
| **Submit Credit Note** / **Reverse Credit Note**                 | Credit note handling on the provider side.    |
| **Reverse Invoice** / **Get Reversal Status**                    | Reversal handling.                            |
| **Upsert Item** / **List Items** / **Link Import Item**          | The item catalogue that service types map to. |
| **Upsert Customer** / **Upsert Supplier**                        | Party records.                                |
| **List Branches**                                                | Registered branches.                          |
| **Pull Imports / Purchases / Notices**                           | Inbound data from KRA.                        |
| **Adjust Stock** / **Transfer Stock**                            | Stock operations, where applicable.           |
| **Sales Summary Report** / **List Verifications**                | Reporting and verification.                   |

Operations can also be run individually from the manual capability runner for diagnosis, with a
payload builder and the last operation response shown.

## Re-filing

**Re-file** resubmits an invoice that eTIMS has already accepted.

<Warning>
  Re-filing an accepted invoice reports it to KRA a **second time**, which double-reports the VAT.
  The platform has no credit-note-to-KRA path yet, so this is not self-correcting. Use re-file only
  when you have confirmed the first submission is genuinely not on record with KRA.
</Warning>

The same limitation applies to crediting: raising a credit note against an accepted invoice
corrects your books but does not correct the KRA filing. Coordinate with whoever owns tax
compliance before crediting a certified invoice. See [Adjustments](/guides/adjustments).

## Tax schedule and withholding

The tax module also covers the **tax schedule** and **withholding tax** surfaces, for tracking what
is due and what has been withheld on payments.

## Monthly tax routine

<Steps>
  <Step title="Clear the failed queue">
    Filter provider mappings by failed status and resolve each one. Most failures are tax-class or
    item-mapping issues, not connectivity.
  </Step>

  <Step title="Confirm every issued invoice was submitted">
    An invoice with no submission is an unreported sale.
  </Step>

  <Step title="Reconcile the sales summary">
    Compare the provider's sales summary against your revenue for the period.
  </Step>

  <Step title="Review credits">
    Any credit note against a certified invoice needs a decision on how it is handled with KRA.
  </Step>

  <Step title="Then close the period">
    See [Accounting periods](/guides/accounting-periods).
  </Step>
</Steps>

## Common problems

| Symptom                                          | Cause and fix                                                                           |
| ------------------------------------------------ | --------------------------------------------------------------------------------------- |
| Submission rejected: unknown item                | The service type is not in the provider's item catalogue. Upsert the item and resubmit. |
| Submission rejected: tax class                   | The service type's tax class does not match its registration. Correct the service type. |
| No submission attempted                          | The invoice is still draft, or the branch has no connection configured.                 |
| Certified receipt missing on an accepted invoice | Refresh the invoice; if it persists, check the mapping's last operation response.       |
| Everything failing at once                       | A credentials or connection problem, not a data problem. Check the connection setup.    |