Receipt types and fields

Fiscal invoices, credit notes and debit notes, and the fields and rules that apply to them

Receipt types

Every sale reported to ZIMRA is a receipt. Set its receipt_type to one of:

receipt_typeUse it toAmounts
FiscalInvoiceRecord a salePositive
CreditNoteReduce an earlier fiscal invoice, such as a refund or a returnNegative
DebitNoteIncrease an earlier fiscal invoicePositive

A Discount line carries the opposite sign to a Sale line: negative on a fiscal invoice or debit note, and positive on a credit note. Payments carry the receipt's sign.

Fields every receipt needs

FieldNotes
trader_invoice_numberYour own invoice number from your ERP or POS, sent to ZIMRA as the receipt's invoice number. See Your invoice number
currencyUSD or ZWG (Zimbabwe Gold). USD is the default in the DigiTax Dashboard
lines_tax_inclusivetrue if your line totals already include tax
linesAt least one line. See Lines
paymentsAt least one payment. Payments must add up to total_cents. Split a payment across several money_types (Cash, Card, MobileWallet, Coupon, Credit, BankTransfer, Other) by sending one entry each
total_centsWhat you expect the receipt to total. DigiTax works out the total from the lines and taxes and rejects a mismatch rather than correcting it (RCPT019)

Optional fields include buyer, notes, print_form (Receipt48 for a 48-character till slip or InvoiceA4), user_name and user_full_name (the cashier).

Amounts are in cents

Amounts are whole numbers of cents (150 is 1.50) and quantities are whole numbers of thousandths (quantity_milli: 2000 is 2). Send them exactly as they should be signed.

Your invoice number (trader_invoice_number)

trader_invoice_number is required on the API and is the request's idempotency key:

  • Retrying with the same number returns the receipt already issued. It never issues a second one. Retry safely after a timeout.
  • The same number with a different sale returns 409 Conflict.
  • A number already sent to ZIMRA for another receipt on the device returns 409 Conflict.
  • A number in the form of a DigiTax-generated invoice number (<device ID>-<number>) returns 400.

DigiTax also gives every receipt its own invoice_number (the device ID and the receipt's global number, such as 25415-144).

Lines

FieldNotes
line_typeSale or Discount
nameThe goods or service, as printed on the receipt
quantity_milliQuantity in thousandths
price_centsOptional unit price. If you send it, the line total must be the price times the quantity, rounded to the cent (RCPT024), and it carries the line's sign (RCPT022)
total_centsLine total, including tax when lines_tax_inclusive is true
tax_idOne of your device's taxes. See Taxes
tax_codeThe tax's code, if it has one. Set it on every line or on none
hs_codeSee HS codes

With POST /detailed-receipts, a line names an item instead (item_id, or an inline item), and its name, HS code and tax come from that item.

Taxes (tax_id)

ZIMRA assigns tax IDs per device, in the device's configuration. Read yours from GET /resources/tax-categories instead of hard-coding them. A receipt is checked against exactly that list, including each tax's valid_from and valid_till. The 517 in our examples is the test device's standard 15.5% rate, and won't be the same on your production device.

An exempt tax (exempt: true) has no rate. It is not the same as a zero-rated tax, whose tax_percent is 0.

HS codes (hs_code)

An HS code is 4 or 8 digits. Whether it is required depends on whether you are VAT-registered, which GET /fdms-info shows as a non-empty vat_number:

TaxpayerSale lineDiscount line
VAT-registeredRequired (RCPT047). Must be 8 digits when the line's tax is 0% or exempt (RCPT048)Optional, 4 or 8 digits
Not VAT-registeredOptionalOptional

GET /resources/hs-codes lists the 4-digit HS 2022 headings. The 8-digit codes are Zimbabwe's national tariff lines from the Zimbabwe Customs and Excise Tariff, which that list doesn't hold. DigiTax checks the code's format only, so any well-formed code is accepted.

The buyer

The buyer is optional, and every field in it is optional. It decides what ZIMRA receives:

  • ZIMRA is sent the buyer only when it has both a tin (10 digits) and a register_name. ZIMRA grades buyer data without both Red (RCPT043).
  • A buyer with no tin, such as an unregistered individual, is printed on the receipt but not sent to ZIMRA. The receipt is then an ordinary sale to an unregistered buyer.
  • A tin without a register_name fails validation.

vat_number is 9 digits. province is free text. GET /resources/provinces lists names you can suggest.

🚧

Missing buyer details are a common cause of Red receipts

If you collect a buyer's TIN, always send their registered name with it. Otherwise leave the buyer's TIN out.

Credit and debit notes

A credit or debit note corrects an earlier fiscal invoice. It must:

  • say why in notes (RCPT034)
  • name its original by exactly one of:
    • original_receipt_id: the original's DigiTax ID, if it was issued through DigiTax on the same device
    • original_invoice_number: the original's trader_invoice_number, or its invoice_number if it had none
    • credit_debit_note: ZIMRA's reference, for an original not issued through DigiTax (before you onboarded, or from another system). Give either its ZIMRA receipt_id, or its receipt_global_no and fiscal_day_no
  • use the original's currency (RCPT042) and only taxes the original used (RCPT036)
  • correct an original issued in the last 12 months (RCPT033)

A credit note can't take back more than is left of its original (RCPT035). A fiscal invoice names no original (RCPT029).

For an original issued through DigiTax, a reference that doesn't exist returns 404. An original that isn't a fiscal invoice, or was issued on another device, returns 412.

Learn more


Did this page help you?