Fiscal days and the close of day

How ZIMRA fiscal days work, how DigiTax opens and closes them for you, and what stops a day from closing

A fiscal day is not a calendar day

ZIMRA groups receipts into fiscal days. A fiscal day starts when it is opened and lasts at most tax_payer_day_max_hrs hours from then, a limit ZIMRA sets in your device's configuration (GET /fdms-info). It can run past midnight. For example, with a 24-hour limit, a day opened at 09:00 on Monday takes receipts until 09:00 on Tuesday at the latest, and all of them belong to Monday's fiscal day.

Each day has a fiscal_day_no, one higher than the last. Each receipt's receipt_counter restarts at 1 on each new day, while its receipt_global_no keeps counting across days.

DigiTax opens and closes days for you

You never open or close a fiscal day yourself:

  • Opening. If no day is open, your next receipt opens one. There is no separate call to open a day.
  • Closing. DigiTax starts closing the day automatically at its warn_at time, which is ZIMRA's warning point before the limit, or at closes_at if there is no warn_at. If ZIMRA refuses the close, DigiTax tries again every few minutes until the day runs out.

GET /fiscal-days and GET /fiscal-days/{fiscal_day_id} show each day's times:

FieldMeaning
statusFiscalDayOpening (waiting for ZIMRA to confirm the open), FiscalDayOpened, FiscalDayCloseInitiated, FiscalDayCloseFailed or FiscalDayClosed
opened_atWhen the day opened
warn_atWhen DigiTax starts closing the day automatically
closes_atWhen the day reaches ZIMRA's limit
closed_atWhen the day closed. Absent while it is open
receipt_counterReceipts issued on the day so far
closing_error_codeZIMRA's reason, if a close failed
📘

Expect a short 412 while a day closes

While DigiTax is closing the day, POST /receipts returns 412 Precondition Failed. This usually lasts a few seconds. Retry with the same trader_invoice_number, and the receipt goes onto the next day.

The close-of-day caveat

ZIMRA will only close a fiscal day once it has every receipt of that day and none of them is graded Red or Grey.

🚧

A day holding a Red or Grey receipt can't be closed through FDMS

  • Grey means a gap in the receipt chain: ZIMRA is missing an earlier receipt. It clears by itself once the missing receipt reaches ZIMRA, and then the day can close.
  • Red never clears. The day can then only be closed in ZIMRA's portal. Contact DigiTax support, who will help you close it there. DigiTax picks the close up from ZIMRA and moves on to the next day.

Receipts that haven't reached ZIMRA also hold the close until they are sent. If sending has halted, the day can't close until it resumes. See When sending halts.

Act on a Red receipt as soon as you hear about it, through the zimra.receipt.flagged callback or a FLAGGED status, because the day keeps running towards closes_at. Receipts dated after closes_at break ZIMRA's day-length rule (RCPT041).

Receipts left on a day closed in the portal

When a day is closed in ZIMRA's portal, any of its receipts that hadn't reached ZIMRA yet can't be sent as they are. DigiTax support moves them onto the open day and signs them again. Their fiscal_day_no, receipt_counter, receipt_date, verification_code and qr_url change, but their receipt_global_no doesn't. DigiTax sends the zimra.receipt.restamped callback for each one. Replace any copy you have already printed or sent to the buyer, because the old verification code no longer checks out with ZIMRA.

Until then, GET /fdms-info shows these receipts in receipt_submission.stranded_receipt_count.

X and Z reports

GET /fiscal-days/{fiscal_day_id}/report returns ZIMRA's daily report for a day:

  • An X report (kind: X_REPORT) is the running totals of a day that is still open. It changes as receipts are issued.
  • A Z report (kind: Z_REPORT) is the final totals of a closed day. It no longer changes, and it carries the day's device and ZIMRA signatures.

Both cover one whole fiscal day. A date filter such as receipt_date_from and receipt_date_to on GET /receipts selects receipts by date instead, so it can take in parts of two fiscal days. To get exactly one day's receipts, filter by fiscal_day_id.

For a day closed in ZIMRA's portal, the Z report's reconciliation_mode is Manual, and its totals and document counts are ZIMRA's own figures. For a test business on the shared test device, own_receipts_only is true: the totals cover only your receipts, and the day's signatures are left out.

The report endpoint returns 412 while the day is still being opened.


Did this page help you?