---
updatedAt: 2026-08-28T22:30:17.000Z
agentTools:
  projectIndex: https://developer.wafeq.com/llms.txt
---

# Manage the invoice lifecycle

Create, deliver, adjust, report, and collect invoices while keeping Wafeq’s accounting records consistent.

# 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

| Need                                                  | Use                                                              |
| ----------------------------------------------------- | ---------------------------------------------------------------- |
| Create one accounting invoice                         | [Create invoice](/reference/invoices_create)                     |
| Create or send many email/PDF invoices in one request | [Send invoices (bulk)](/reference/api_invoices_bulk_send_create) |
| Create a B2C simplified tax invoice                   | [Simplified invoices](/reference/simplified-invoices)            |
| Start from an accepted quote                          | [Convert quote to invoice](/reference/quotes_invoice_create)     |
| Correct an issued sale                                | [Credit notes](/reference/credit-notes)                          |

## Create an invoice directly

```bash
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](/reference/invoices_download_retrieve).
* For supported organizations and document types, submit it with [Report invoice to tax authority](/reference/invoices_tax_authority_report_create).
* For bulk email delivery, use [Send invoices (bulk)](/reference/api_invoices_bulk_send_create).

Saudi Arabia Phase 2 integrations have additional requirements. Review [Wafeq Public API vs ZATCA API](/docs/wafeq-public-api-vs-zatca-api) before selecting the compliance path.

## Record collection

Create a [payment](/reference/payments_create) 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](/docs/design-a-reliable-integration) for retries and idempotency.