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_type | Use it to | Amounts |
|---|---|---|
FiscalInvoice | Record a sale | Positive |
CreditNote | Reduce an earlier fiscal invoice, such as a refund or a return | Negative |
DebitNote | Increase an earlier fiscal invoice | Positive |
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
| Field | Notes |
|---|---|
trader_invoice_number | Your own invoice number from your ERP or POS, sent to ZIMRA as the receipt's invoice number. See Your invoice number |
currency | USD or ZWG (Zimbabwe Gold). USD is the default in the DigiTax Dashboard |
lines_tax_inclusive | true if your line totals already include tax |
lines | At least one line. See Lines |
payments | At 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_cents | What 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)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
| Field | Notes |
|---|---|
line_type | Sale or Discount |
name | The goods or service, as printed on the receipt |
quantity_milli | Quantity in thousandths |
price_cents | Optional 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_cents | Line total, including tax when lines_tax_inclusive is true |
tax_id | One of your device's taxes. See Taxes |
tax_code | The tax's code, if it has one. Set it on every line or on none |
hs_code | See 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)
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)
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:
| Taxpayer | Sale line | Discount line |
|---|---|---|
| VAT-registered | Required (RCPT047). Must be 8 digits when the line's tax is 0% or exempt (RCPT048) | Optional, 4 or 8 digits |
| Not VAT-registered | Optional | Optional |
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 aregister_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
tinwithout aregister_namefails 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 receiptsIf 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 deviceoriginal_invoice_number: the original'strader_invoice_number, or itsinvoice_numberif it had nonecredit_debit_note: ZIMRA's reference, for an original not issued through DigiTax (before you onboarded, or from another system). Give either its ZIMRAreceipt_id, or itsreceipt_global_noandfiscal_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
- Create a receipt
- Receipt statuses and validation
- POST /receipts in the API reference
Updated about 2 hours ago