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_attime, which is ZIMRA's warning point before the limit, or atcloses_atif there is nowarn_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:
| Field | Meaning |
|---|---|
status | FiscalDayOpening (waiting for ZIMRA to confirm the open), FiscalDayOpened, FiscalDayCloseInitiated, FiscalDayCloseFailed or FiscalDayClosed |
opened_at | When the day opened |
warn_at | When DigiTax starts closing the day automatically |
closes_at | When the day reaches ZIMRA's limit |
closed_at | When the day closed. Absent while it is open |
receipt_counter | Receipts issued on the day so far |
closing_error_code | ZIMRA's reason, if a close failed |
Expect a short 412 while a day closesWhile 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.
Updated about 2 hours ago