Invoices and e-invoicing

An invoice here is a tax document issued under ZATCA's e-invoicing rules: a tax invoice, a credit note or a debit note. It starts as a draft you can edit or delete freely, then it is issued: it gets its sequential number, its cryptographic stamp and its QR code, and goes to ZATCA. After that it cannot be changed; a correction is a credit or debit note that references it. The feature is explained in full in E-Invoices (ZATCA).

Finding and reading invoices

invoices_list

Lists your organization's invoices, credit notes and debit notes, newest first. Filter by stage, ZATCA outcome, document or kind, the sales order they bill or the invoice a note corrects, or search by free text.

Read-only · scope invoices.read · roles: owner, admin, sales, purchasing, viewer · Pro and Enterprise plans

{
  "status": "issued",
  "zatca_status": "rejected",
  "page_size": 50
}

Returns: A page of invoices, each with its number, UUID, kind, stage, ZATCA outcome, buyer, totals and the sales order and tender it is linked to, and the total count.

• Drafts also carry zatca_status none. Add status: issued to find only the invoices issued without a live unit.

invoices_get

Returns one invoice in full: header, lines, buyer, totals, ZATCA's outcome and messages and the QR code, with the sales order, quotation and tender it is linked to and the notes that correct it. For a draft it also lists what is still missing before it can be issued.

Read-only · scope invoices.read · roles: owner, admin, sales, purchasing, viewer · Pro and Enterprise plans

Returns: An object with invoice, items, readiness_issues, qr_image (a PNG data URI, empty for a draft), sales_order, quotation, tender, original_invoice, corrections (the notes that correct it), egs (the unit's environment and status) and events (the invoice's 50 most recent activity rows).

• readiness_issues is a list of codes for what a draft lacks, and it is empty once issued. Codes starting with seller_ belong to the organization record in settings and cannot be fixed on the invoice. The other codes name a missing buyer, line or note field, such as buyer_identity, supply_date, original_invoice and line_exemption_reason.
• ZATCA's messages on a rejection are in invoice.zatca_error and invoice.zatca_response. The signed and the cleared XML are not in this reply; download them with invoice_xml.

Drafts

A draft has no number, hash or XML. Save it half-filled if you like: nothing is checked against ZATCA's requirements until you issue, and invoices_get shows what is missing.

invoices_create

Saves a tax invoice, credit note or debit note as a draft with at least one line. Nothing is numbered, signed or sent until you issue it. Name a customer profile to fill the buyer's name, identifier and address, and send any field you want to win over the profile.

Changes data · scope invoices.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "customer_id": 214,
  "transaction_type": "standard",
  "sales_order_id": 87,
  "supply_date": "2026-10-04",
  "payment_means_code": "30",
  "items": [
    {
      "description": "Disposable syringe 5 ml, box of 100",
      "quantity": 40,
      "unit_code": "BX",
      "unit_price": 38.5,
      "vat_category": "Z",
      "vat_exemption_code": "VATEX-SA-35"
    },
    {
      "description": "Delivery to Riyadh warehouse",
      "quantity": 1,
      "unit_price": 150
    }
  ]
}

Returns: The new draft's ID as invoice_id. Read it back with invoices_get.

• Totals are calculated per line and rounded to the cent: the net is quantity times unit price minus the discount, VAT is applied at the line's rate, and the invoice totals are the sums of its lines.
• A standard invoice needs the buyer's VAT number or another identifier, a street, building number, city and postal code, and a supply date before it can be issued. A simplified invoice needs only the customer name. A zero-rated medical line takes category Z with VATEX-SA-35.
• A customer, sales order, quotation, product or original invoice that is not found in your organization, or a tender you cannot see, answers 404. A note whose original is not an issued tax invoice answers 400.

invoices_update

Changes a draft. Only the fields you send change, null clears a field that can be empty, and items, when sent, replaces all the lines. An issued invoice cannot be changed: issue a credit or debit note that references it instead.

Changes data · scope invoices.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

{
  "id": 311,
  "supply_date": "2026-10-05",
  "buyer_vat_number": "300012345600003"
}

Returns: The draft's ID as invoice_id.

• An issued invoice answers 409 whatever you send, and an invoice that is not in your organization answers 404.
• Sending items deletes the current lines and puts the new ones in their place, so send the whole list, not only the lines that changed.

invoices_delete

Deletes a draft. An issued invoice is a tax record and cannot be deleted. The deletion stays in the activity log.

Deletes or overwrites data · scope invoices.write · roles: owner, admin, sales, purchasing · Pro and Enterprise plans

Returns: A confirmation (ok: true).

• An issued invoice answers 409. Correct an issued invoice with a credit or debit note.

Issuing and sending to ZATCA

Issuing is the one step that cannot be undone, and only an admin or the owner may take it.

invoices_issue

Issues a draft: it assigns the sequential number and the issue date and time (Riyadh), builds and stamps the invoice XML, adds the QR code, freezes the document and sends it to ZATCA, for clearance if it is a standard invoice or reporting if it is a simplified one. This cannot be undone.

Changes data · scope invoices.write · roles: owner, admin · Pro and Enterprise plans

Returns: invoice_id, invoice_number, signed (false when issued without a live unit), zatca_status (cleared, reported, rejected, pending or none), zatca_has_warnings and zatca_error (ZATCA's messages on a rejection).

• A draft that lacks something ZATCA requires answers 400 with issues, a list of field codes, and stays a draft with no number used. Read readiness_issues from invoices_get before issuing.
• With no live e-invoicing unit the invoice is still issued, with a five-field QR code and zatca_status none, and it can never be sent to ZATCA afterwards. Set the unit up first if the invoice must reach ZATCA.
• pending means ZATCA could not be reached: the invoice is issued and stamped, and invoices_submit sends the same file again. A rejected invoice keeps its number, and if the cause was on the unit's side and is fixed, it can be sent again.
• Answers 409 when the invoice is already issued, and when another invoice of your organization is being issued at that moment (try again shortly).

invoices_submit

Sends an issued invoice to ZATCA again with the same stored, stamped file, so its hash does not change. Use it for an invoice left pending by an outage, or rejected for a reason on the unit's side that has since been fixed.

Changes data · scope invoices.write · roles: owner, admin · Pro and Enterprise plans

Returns: invoice_id, invoice_number, signed, zatca_status, zatca_has_warnings and zatca_error, as in invoices_issue.

• Answers 409 for a draft, for an invoice issued without a live unit (it carries no stamp), for an invoice ZATCA has already accepted (cleared or reported), and when the unit that stamped it is no longer live.

Files and the archive

invoice_pdf

Prints the invoice as a PDF in Arabic with English, with its QR code and VAT breakdown. A draft prints as a watermarked preview without a QR code.

Read-only · scope invoices.read · roles: owner, admin, sales, purchasing, viewer · Pro and Enterprise plans

Returns: A PDF file with filename, content_type, size_bytes and the content as base64 in base64.

• A file over 4 MB is not embedded in the reply; the tool answers with an error that names the REST endpoint to download it from. Every download is recorded in the activity log.

invoice_xml

Returns an issued invoice's signed XML, the very file ZATCA received (UBL 2.1). With cleared: true it returns the copy ZATCA stamped at clearance instead.

Read-only · scope invoices.read · roles: owner, admin, sales, purchasing, viewer · Pro and Enterprise plans

Returns: An XML file with filename, content_type, size_bytes and the content as base64 in base64.

• A draft has no XML and answers 404, and so does cleared: true for an invoice ZATCA returned no cleared copy of. Every download is recorded in the activity log.

invoice_archive_zip

Packs the signed XML of every issued invoice, credit note and debit note into one ZIP, for your archive or an auditor. Files are named the way ZATCA asks you to keep them, and a manifest.json lists what is inside.

Read-only · scope invoices.read · roles: owner, admin · Pro and Enterprise plans

Returns: A ZIP file with filename, content_type, size_bytes and the content as base64 in base64. Each document is a file named <VAT number>_<issue date>T<issue time>_<invoice number>.xml, with ZATCA's stamped copy beside it as .cleared.xml where held, plus manifest.json with numbers, UUIDs, counters and hashes.

• A window with more than 5,000 documents answers 413: narrow it with from and to. A window with no issued invoices answers 404.
• An archive over 4 MB is not embedded in the reply; the tool answers with an error that names the REST endpoint to download it from. Every export is recorded in the activity log.

Activity log and verification

The platform writes the activity log itself and nobody can edit or delete a row, each row being chained to the previous one by hash. A verification tool checks the records as a whole.

invoice_events_list

Lists the e-invoicing activity log, newest first: every draft created, edited or deleted, each issue and submission to ZATCA, each PDF, XML and archive download, each verification and every step in the unit's life. Each row says who did it and through which channel.

Read-only · scope invoices.read · roles: owner, admin, sales, purchasing, viewer · Pro and Enterprise plans

{
  "scope": "invoice",
  "event": "invoice.issued",
  "from": "2026-10-01",
  "page_size": 25
}

Returns: A page of rows, each with id, invoice_id, invoice_number, event, actor_email, channel (app, api or system), detail, created_at, prev_hash and entry_hash, and the total count.

• The channel app is the web app, api is any call through the API, MCP or the assistants on a member's behalf, and system is the platform acting on its own.
• A row without an invoice_id is about the unit, an archive export or a verification.

zatca_chain_verify

Proves the e-invoicing records intact. It re-hashes every issued document from its stored XML and checks each stamp against the certificate inside the file, each invoice's link to the previous one and the counter sequence, the unit's counter and last hash, and the activity log's own chain. It changes nothing except adding one chain.verified row to the log. Run it before an audit.

Read-only · scope settings.write · roles: owner · Pro and Enterprise plans

No parameters.

Returns: An object with ok, checked_at, invoices (documents examined), chains (one per unit that stamped documents, each with ok, issues, last_hash and highest_icv), phase1 (documents issued without a unit), unit (the counter and last-hash checks) and log (the activity log's chain).

• Each problem in issues names the invoice and a code for what does not hold: hash_mismatch, signature_invalid, signature_missing, pih_mismatch, icv_gap, icv_duplicate, xml_row_mismatch, xml_missing or certificate_unreadable.
• It needs the write scope settings.write although none of your invoice data changes, because the run is recorded in the activity log.