Issue a receipt

Validates, numbers, signs and stores the receipt on the open fiscal day; it is sent to ZIMRA in the background, so it is PENDING until ZIMRA accepts it. trader_invoice_number, your own invoice number, is required and is the idempotency key: retrying with the same number returns the receipt already issued rather than issuing another, and the same number with a different sale returns 409. A trader_invoice_number already sent to ZIMRA for another receipt on the device returns 409. A receipt that fails validation returns 400 with message "the receipt failed validation", metadata.codes (comma-separated rule codes, e.g. RCPT019) and metadata.violations (a JSON array of {code, colour, message, line_no, meta}). There is no separate open: the first receipt when no fiscal day is open opens one. Returns 412 if the day can't be opened (no ZIMRA registration, or a device that is not active or has no active certificate yet), or while DigiTax is closing it automatically - usually a few seconds, so retry.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

All amounts are integer cents and quantities thousandths, exactly as they are signed. The totals are checked against what DigiTax computes - a mismatch is rejected, never corrected.

string
enum
required

FiscalInvoice for a sale, CreditNote to reduce and DebitNote to increase an earlier fiscal invoice (both name it by one of original_receipt_id, original_invoice_number or credit_debit_note)

Allowed:
string
enum
required

ZIMRA receipts are taken in USD or ZWG

Allowed:
string
required
length between 1 and 50

Required. The invoice number from your own system (ERP or POS), sent to ZIMRA as the receipt's invoiceNo. It is the request's idempotency key - a retry with the same number returns the receipt already issued, and the same number with a different sale returns 409 - and it must be unique across the device: a number already sent for another receipt returns 409, and one in the form of a generated invoice_number (

boolean
required

Whether the line totals already include tax

lines
array of objects
required
length ≥ 1

The goods or services sold; at least one

lines*
payments
array of objects
required
length ≥ 1

How the sale was paid; at least one

payments*
int64
required

What you expect the receipt to total, in cents; a mismatch is rejected (RCPT019)

buyer
object

The buyer printed on the receipt; optional, and every field is optional within it. ZIMRA is sent the buyer only when it has a tin and a register_name (ZIMRA grades buyer data without both Red, RCPT043). A buyer without a tin, such as an unregistered individual, is kept on the receipt and its printout but not sent to ZIMRA, so the receipt is an ordinary sale to an unregistered buyer. A tin without a register_name fails validation.

string
length ≤ 500

Free-text notes sent to ZIMRA with the receipt; required on a credit or debit note, to say why it was issued

string
length ≤ 128

On a credit or debit note, the id of the fiscal invoice it corrects. It must be one of yours, issued through DigiTax on the same device; 404 if there is none, 412 if it isn't a FiscalInvoice or was issued on another device. A note names its original by exactly one of original_receipt_id, original_invoice_number and credit_debit_note; an invoice names none.

string
length ≤ 50

On a credit or debit note, the fiscal invoice it corrects by its invoice number: its trader_invoice_number if it had one, otherwise its invoice_number. Checked as original_receipt_id is.

credit_debit_note
object

ZIMRA's own reference to the receipt a credit or debit note corrects, for an original that wasn't issued through DigiTax (before onboarding, or from another system): either ZIMRA's receipt_id of the original, or its receipt_global_no and fiscal_day_no. Name an original issued through DigiTax by original_receipt_id or original_invoice_number instead.

string
enum

The format the receipt is printed in - a 48-character-wide till slip or an A4 invoice. ZIMRA's default applies when omitted

Allowed:
string
length ≤ 100

Username of the cashier issuing the receipt, sent to ZIMRA

string
length ≤ 250

Full name of that cashier; defaults to user_name when only that is given

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json