Manage the invoice lifecycle

Use the accounting invoice endpoints when Wafeq should own the receivable, ledger postings, payment status, and reporting context.

Choose the right invoice path

Create an invoice directly

curl --request POST "https://api.wafeq.com/v1/invoices/" \
  --header "Authorization: Api-Key <API_KEY>" \
  --header "Content-Type: application/json" \
  --header "X-Wafeq-Idempotency-Key: invoice-<SOURCE_ID>" \
  --data '{
    "contact": "<CUSTOMER_CONTACT_ID>",
    "currency": "SAR",
    "invoice_date": "2026-08-29",
    "invoice_due_date": "2026-09-28",
    "invoice_number": "INV-2048",
    "reference": "ORDER-2048",
    "external_id": "order_2048",
    "tax_amount_type": "TAX_EXCLUSIVE",
    "line_items": [
      {
        "description": "Implementation services",
        "account": "<REVENUE_ACCOUNT_ID>",
        "quantity": 10,
        "unit_amount": 500,
        "tax_rate": "<TAX_RATE_ID>",
        "cost_center": "<COST_CENTER_ID>"
      }
    ]
  }'

The response contains the Wafeq invoice ID, calculated amount, tax amount, balance, and line items. Store the ID; use it for PDF downloads, payments, tax reporting, and adjustments.

Deliver and report the invoice

• Download the current PDF with Download invoice PDF.
• For supported organizations and document types, submit it with Report invoice to tax authority.
• For bulk email delivery, use Send invoices (bulk).

Saudi Arabia Phase 2 integrations have additional requirements. Review Wafeq Public API vs ZATCA API before selecting the compliance path.

Record collection

Create a payment with invoice_payments entries. One payment can allocate amounts to the relevant invoice records; each allocation identifies the invoice and the amount being settled.

After the payment succeeds, retrieve the invoice again instead of calculating its accounting status only in your application.

Adjust an issued invoice

Use a credit note when goods are returned, the price is reduced, or an issued invoice must be reversed. Preserve the original invoice and link your source-system adjustment to the Wafeq credit note.

Avoid changing posted history merely to make the current balance look right. Accounting documents form an audit trail.

Synchronize state

List endpoints expose filters such as creation or modification timestamps where supported. A reliable sync should:

1. Pull records changed since the last completed checkpoint.
2. Upsert by Wafeq ID.
3. Advance the checkpoint only after the entire page set succeeds.
4. Re-read documents after payments, tax reporting, or credit notes change their state.

See Design a reliable integration for retries and idempotency.