Waqti Docs

English

العربية

English

العربية

Invoices API ​

Complete reference for Invoice endpoints. Responses include match_status for three-way matching (full_match, partial_match, mismatch, pending_grn) and payment_status for settlement (unpaid, partial, paid, overdue).

See also: Invoice Management User Guide.

List Invoices ​

http
GET /v1/invoices

Query Parameters ​

ParameterTypeDescription
statusstringFilter by workflow status: draft, submitted, pending, approved, paid, cancelled
vendor_idintegerFilter by vendor
purchase_order_idintegerFilter by linked purchase order id (this is the PO record id; the same value is often called po_id in client apps)
match_statusstringFilter by three-way match: full_match, partial_match, mismatch, pending_grn
from_datedateInvoices with invoice_date on or after this date (ISO 8601)
to_datedateInvoices with invoice_date on or before this date (ISO 8601)
sort_bystringSort field (default: created_at)
sort_orderstringasc or desc (default: desc)
per_pageintegerPage size (default: 15)

Example Request ​

bash
curl -X GET "https://api.waqti.sa/v1/invoices?status=submitted&vendor_id=5&purchase_order_id=42&from_date=2026-01-01&to_date=2026-03-31&per_page=20" \
  -H "Authorization: Bearer 3|a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Example Response ​

json
{
  "data": [
    {
      "id": 1088,
      "invoice_number": "INV-001088",
      "vendor_invoice_number": "VND-2026-0142",
      "status": "submitted",
      "payment_status": "unpaid",
      "match_status": "full_match",
      "currency": "SAR",
      "subtotal": 20000.00,
      "vat_amount": 3000.00,
      "total": 23000.00,
      "invoice_date": "2026-03-10T00:00:00Z",
      "due_date": "2026-04-09T00:00:00Z",
      "vendor": {
        "id": 5,
        "name": "ABC Supplies Co."
      },
      "purchase_order": {
        "id": 42,
        "po_number": "PO-2026-0042"
      },
      "created_at": "2026-03-11T08:15:00Z"
    },
    {
      "id": 1089,
      "invoice_number": "INV-001089",
      "vendor_invoice_number": "VND-2026-0143",
      "status": "submitted",
      "payment_status": "unpaid",
      "match_status": "pending_grn",
      "currency": "SAR",
      "subtotal": 8500.00,
      "vat_amount": 1275.00,
      "total": 9775.00,
      "invoice_date": "2026-03-12T00:00:00Z",
      "due_date": "2026-04-11T00:00:00Z",
      "vendor": {
        "id": 5,
        "name": "ABC Supplies Co."
      },
      "purchase_order": {
        "id": 43,
        "po_number": "PO-2026-0043"
      },
      "created_at": "2026-03-12T11:40:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 2,
    "per_page": 20,
    "total": 35
  }
}

Create Invoice ​

http
POST /v1/invoices

Request Body ​

json
{
  "vendor_id": 5,
  "po_id": 42,
  "invoice_number": "VND-2026-0142",
  "invoice_date": "2026-03-10",
  "due_date": "2026-04-09",
  "currency": "SAR",
  "line_items": [
    {
      "description": "Laptop docking stations",
      "quantity": 10,
      "unit": "unit",
      "unit_price": 450.00,
      "vat_rate": 15
    },
    {
      "description": "USB-C cables (2m)",
      "quantity": 50,
      "unit": "piece",
      "unit_price": 35.00,
      "vat_rate": 15
    }
  ],
  "subtotal": 6250.00,
  "vat_amount": 937.50,
  "total": 7187.50,
  "description": "Hardware shipment per PO-2026-0042"
}

po_id is the linked purchase order id. Payloads may use purchase_order_id instead of po_id with the same meaning.

Response ​

json
{
  "data": {
    "id": 1090,
    "invoice_number": "INV-001090",
    "vendor_invoice_number": "VND-2026-0142",
    "status": "draft",
    "payment_status": "unpaid",
    "match_status": "pending_grn",
    "vendor_id": 5,
    "purchase_order_id": 42,
    "currency": "SAR",
    "subtotal": 6250.00,
    "vat_amount": 937.50,
    "total": 7187.50,
    "invoice_date": "2026-03-10T00:00:00Z",
    "due_date": "2026-04-09T00:00:00Z",
    "line_items": [
      {
        "id": 501,
        "line_number": 1,
        "description": "Laptop docking stations",
        "quantity": 10,
        "unit": "unit",
        "unit_price": 450.00,
        "vat_rate": 15,
        "vat_amount": 675.00,
        "line_total": 5175.00
      },
      {
        "id": 502,
        "line_number": 2,
        "description": "USB-C cables (2m)",
        "quantity": 50,
        "unit": "piece",
        "unit_price": 35.00,
        "vat_rate": 15,
        "vat_amount": 262.50,
        "line_total": 2012.50
      }
    ],
    "created_at": "2026-03-14T09:00:00Z"
  }
}

Get Invoice ​

http
GET /v1/invoices/{id}

Response ​

json
{
  "data": {
    "id": 1088,
    "invoice_number": "INV-001088",
    "vendor_invoice_number": "VND-2026-0142",
    "status": "approved",
    "payment_status": "partial",
    "match_status": "full_match",
    "vendor": {
      "id": 5,
      "name": "ABC Supplies Co.",
      "email": "sales@abcsupplies.com",
      "vat_number": "300000000000003"
    },
    "purchase_order": {
      "id": 42,
      "po_number": "PO-2026-0042",
      "status": "completed",
      "total_inc_vat": 23000.00
    },
    "goods_receipt": {
      "id": 17,
      "gr_number": "GR-2026-0017",
      "status": "complete"
    },
    "currency": "SAR",
    "subtotal": 20000.00,
    "vat_amount": 3000.00,
    "total": 23000.00,
    "amount_paid": 10000.00,
    "amount_due": 13000.00,
    "invoice_date": "2026-03-10T00:00:00Z",
    "due_date": "2026-04-09T00:00:00Z",
    "description": "Q1 IT peripherals",
    "line_items": [
      {
        "id": 495,
        "line_number": 1,
        "description": "Network switches (24-port)",
        "quantity": 4,
        "unit": "unit",
        "unit_price": 2500.00,
        "vat_rate": 15,
        "vat_amount": 1500.00,
        "line_total": 11500.00
      },
      {
        "id": 496,
        "line_number": 2,
        "description": "Rack mounting kits",
        "quantity": 4,
        "unit": "unit",
        "unit_price": 1500.00,
        "vat_rate": 15,
        "vat_amount": 900.00,
        "line_total": 6900.00
      }
    ],
    "match_summary": {
      "po_variance_pct": 0.0,
      "gr_variance_pct": 0.0,
      "last_matched_at": "2026-03-11T14:05:00Z"
    },
    "approved_by": {
      "id": 22,
      "name": "Noura Al-Faisal"
    },
    "approved_at": "2026-03-11T14:10:00Z",
    "created_at": "2026-03-11T08:15:00Z",
    "updated_at": "2026-03-11T14:10:00Z"
  }
}

Update Invoice ​

http
PUT /v1/invoices/{id}

WARNING

Invoices that are already approved or paid cannot be updated; use credit notes or payment workflows instead.

Request Body ​

json
{
  "invoice_number": "VND-2026-0142-A",
  "invoice_date": "2026-03-11",
  "due_date": "2026-04-15",
  "description": "Corrected invoice date and terms",
  "line_items": [
    {
      "id": 495,
      "quantity": 5,
      "unit_price": 2480.00
    },
    {
      "description": "Spare SFP modules",
      "quantity": 8,
      "unit": "piece",
      "unit_price": 190.00,
      "vat_rate": 15
    }
  ],
  "subtotal": 13920.00,
  "vat_amount": 2088.00,
  "total": 16008.00
}

Response ​

json
{
  "data": {
    "id": 1088,
    "invoice_number": "INV-001088",
    "vendor_invoice_number": "VND-2026-0142-A",
    "status": "submitted",
    "payment_status": "unpaid",
    "match_status": "partial_match",
    "currency": "SAR",
    "subtotal": 13920.00,
    "vat_amount": 2088.00,
    "total": 16008.00,
    "invoice_date": "2026-03-11T00:00:00Z",
    "due_date": "2026-04-15T00:00:00Z",
    "description": "Corrected invoice date and terms",
    "updated_at": "2026-03-14T16:22:00Z"
  }
}

Approve Invoice ​

http
POST /v1/invoices/{id}/approve

Records approval after three-way match and policy checks. Typical precondition: match_status is full_match or your tenant rules allow partial_match.

Request Body ​

json
{
  "comments": "Matched to GR-2026-0017 and PO-2026-0042 — approve for payment"
}

Response ​

json
{
  "data": {
    "id": 1088,
    "invoice_number": "INV-001088",
    "status": "approved",
    "payment_status": "unpaid",
    "match_status": "full_match",
    "approved_by": {
      "id": 22,
      "name": "Noura Al-Faisal"
    },
    "approved_at": "2026-03-11T14:10:00Z"
  }
}

Reject Invoice ​

http
POST /v1/invoices/{id}/reject

Request Body ​

json
{
  "reason": "Mismatch: invoice total exceeds PO remaining balance after GRN"
}

Response ​

json
{
  "data": {
    "id": 1091,
    "invoice_number": "INV-001091",
    "status": "cancelled",
    "payment_status": "unpaid",
    "match_status": "mismatch",
    "rejection_reason": "Mismatch: invoice total exceeds PO remaining balance after GRN",
    "rejected_at": "2026-03-15T10:45:00Z"
  }
}

Built by M & L Technologies

Copyright © 2024-2026 Waqti. All rights reserved.