Skip to content

Worked example: key to cleared invoice

Steps 1 to 7, the simplified invoice and the credit note below were run on 2026-10-04 against the demo organisation on the sandbox, in this order. The bodies are what came back, with ids shortened. The demo organisation's VAT number is 300075588700003, ZATCA's sample number, which matches the one certificate the sandbox signs with. That is why its standard invoice clears. Steps 0 and 8 come from an earlier run, on 2026-09-27, with a throwaway key.

The Quickstart explains each step; this page shows the wire.

The interactive reference for every endpoint here is Swagger UI on the sandbox gateway, with an Authorize button that takes a clix_ key:

https://sandbox.api.goclix.ai/v1/api/integrations/docs          Swagger UI
https://sandbox.api.goclix.ai/v1/api/integrations/openapi.json  OpenAPI 3 document

Both are public. Point a client generator at the JSON; use the UI to try a call with your own key.

sequenceDiagram
    participant Admin as Admin, in the app
    participant App as Your system
    participant Clix
    participant ZATCA
    Admin->>Clix: API Keys, Create key
    Clix-->>Admin: key shown once
    App->>Clix: 1 GET /api/usage/current/
    App->>Clix: 2 GET reference data
    App->>Clix: 3 GET /api/devices/, /api/buyers/, /api/items/
    App->>Clix: 4 POST /api/invoices/preview/
    Clix-->>App: 201 computed invoice
    App->>Clix: 5 POST /api/invoices/
    Clix-->>App: 202 location
    Clix->>ZATCA: clearance
    ZATCA-->>Clix: verdict
    App->>Clix: 6 GET location (poll)
    Clix-->>App: zatca_response_status
    App->>Clix: 7 GET pdf-a3
    Admin->>Clix: 8 Revoke

0. Create the key

From the 2026-09-27 run, with a throwaway key.

In the app, an Admin opens API Keys, clicks Create key, enters a Key name and an Access level (Create and view invoices is the default), and clicks Create key. The Copy your key now dialog shows the key once; I have stored it closes it. Steps with screenshots: API keys.

Every call below sends it as:

Authorization: Bearer clix_CdHmGYM_<43-character secret>

The 12-character prefix clix_CdHmGYM is the key's public name; it appears in listings and in the revoke dialog and is safe to log. The 2026-10-04 calls below used the demo organisation's key, written here as clix_….

1. Check the key and the plan

curl -s "$CLIX_API/api/usage/current/" -H "Authorization: Bearer $CLIX_KEY"

200, with these headers and body:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 199
X-RateLimit-Reset: 60
{
  "month": "2026-10-01",
  "subscribed_plan": "demo",
  "invoices_used": 3,
  "invoices_limit": 200,
  "api_calls_used": 0,
  "api_calls_limit": 0,
  "public_api_validations_used": 0,
  "public_api_validations_limit": -1,
  "grace_used": false,
  "grace_exceeded": false,
  "invoices_allowed": true,
  "plan_name": "Demo"
}
Field Type Meaning
month date first day of the current month in Riyadh time (Asia/Riyadh)
subscribed_plan, plan_name string plan slug and display name
invoices_used, invoices_limit int invoices submitted this month, and the allowance; -1 is unlimited
api_calls_used, api_calls_limit int always 0; API calls are not metered
public_api_validations_used, public_api_validations_limit int calls to the public tools this month; -1 is unlimited
grace_used, grace_exceeded bool whether the 10 percent grace above the limit is in use or spent
invoices_allowed bool the one field to branch on before a create

With a wrong or revoked key, the same call returns 401:

{"status": "false", "message": "Invalid or revoked API key"}

2. Read the codes

curl -s "$CLIX_API/api/invoices/vat-categories/"     -H "Authorization: Bearer $CLIX_KEY"
curl -s "$CLIX_API/api/invoices/invoice-type-codes/" -H "Authorization: Bearer $CLIX_KEY"

Each is a map keyed by the enum name, never a list. The first entry of each, verbatim, and the other keys:

{"STANDARD_RATED": {"code": "S",  "description": "Standard Rated", "description_ar": "خاضع للنسبة الأساسية"},
 "ZERO_RATED": {…}, "EXEMPT_FROM_VAT": {…}, "NOT_SUBJECT_TO_VAT": {…}}
{"TAX_INVOICE": {"code": 388, "description": "Tax Invoice", "description_ar": "فاتورة ضريبية"},
 "CREDIT_NOTE": {…}, "DEBIT_NOTE": {…}, "ADVANCE_PAYMENT_INVOICE": {…}}

code is a string for VAT categories and an integer for invoice types and payment means (/api/invoices/payment-means-types/). Full lists: Reference data.

3. Find the device, the buyer and an item

The three lists come back as an object with a named list inside, not as a bare array: devices, buyers, items.

curl -s "$CLIX_API/api/devices/" -H "Authorization: Bearer $CLIX_KEY"
{
  "devices": [
    {
      "counter": 3,
      "common_name": "Clix Demo till",
      "serial_number": "1-AZMX|2-V1|3-6107f3ee-…",
      "location": "Riyadh HQ",
      "unit_name": "https://clix.azmx.sa",
      "industry": "Design",
      "invoice_type": "1100",
      "business_type": "BOTH",
      "seller_id": "4d735e52-…",
      "device_id": "6107f3ee-…",
      "created_at": "2026-10-04",
      "updated_at": "2026-10-04",
      "created_by": "[email protected]",
      "CSIDCertificateData": {"not_valid_before": "2026-10-04T11:19:27Z", "not_valid_after": "2031-10-03T21:00:00Z", "days_until_expiry": 1825, "expiry_status": "valid"},
      "PSIDCertificateData": {"not_valid_before": "2024-01-11T09:19:30Z", "not_valid_after": "2029-01-09T09:19:30Z", "days_until_expiry": 827, "expiry_status": "valid"},
      "ccsid_status": "ISSUED",
      "pcsid_status": "ISSUED",
      "device_status": "pcsid_generated",
      "branch_id": null,
      "branch_name": null,
      "is_branch_device": false,
      "branch_link_status": "not_requested",
      "pending_branch_id": null,
      "pending_branch_name": null
    }
  ],
  "total": 1, "num_pages": 1, "current_page": 1,
  "total_active_devices": 1, "total_ccsid_expired": 0, "total_pcsid_expired": 0,
  "total_active": 1, "total_expiring_soon": 0, "total_expired": 0, "total_unknown": 0
}
Field Use it for
device_id the device of the invoice; the field is not called uuid
seller_id the seller of the invoice; same row, so one read gives both
device_status pcsid_generated is the Active connection in the app; only such a device can issue
invoice_type 1000 standard only, 0100 simplified only, 1100 both
counter the number of invoices this device has signed; a new device reads "No invoices generated yet." instead of 0
PSIDCertificateData.not_valid_after when the production certificate expires
curl -s "$CLIX_API/api/buyers/" -H "Authorization: Bearer $CLIX_KEY"
{
  "buyers": [
    {
      "uuid": "a94027ce-…",
      "buyer_name": "Al Noor Trading",
      "buyer_name_arabic": "",
      "is_from_saudi_arabia": true,
      "is_vat_registered": true,
      "is_active": true,
      "vat_registration_number": "399999999900003",
      "additional_buyer_id": [{"type_id": "CRN", "id_number": "1010010000"}],
      "street": "King Fahd Road", "building_number": "1234", "district": "Al Olaya",
      "city": "Riyadh", "postal_code": "12345", "province_state": "Riyadh", "country": "SA",
      "business_type": {"uuid": "7d9e23b5-…", "code": "1000", "description": "B2B", "type_ar": "شركة إلى شركة"},
      "industry": {"uuid": "0297f443-…", "name": "Design", "name_ar": "تصميم", "is_active": true},
      "seller": "Clix Demo",
      "created_at": "2026-10-04T11:43:58.547Z",
      "…": "contact, phone, e-mail, logo, map and VAT-group fields, empty here"
    }
  ],
  "total": 1, "num_pages": 1, "current_page": 1
}

A standard invoice needs a buyer with a vat_registration_number; this one has it.

curl -s "$CLIX_API/api/items/" -H "Authorization: Bearer $CLIX_KEY"
{"items": [], "total": 0, "page": 1, "page_size": 10, "num_pages": 1}

The demo organisation has no catalogue items, so the invoices below write their lines out with form_lines. Note the paging keys differ: items say page and page_size, devices and buyers say current_page.

4. Preview

The body, invoice.json, exactly as sent:

{
  "device": "6107f3ee-…",
  "seller": "4d735e52-…",
  "buyer": "a94027ce-…",
  "type_code": 388,
  "transaction_code": "0100000",
  "issue_date": "2026-10-01",
  "issue_time": "10:00:00",
  "supply_date": "2026-10-01",
  "supply_end_date": "2026-10-01",
  "currency": "SAR",
  "exchange_rate": 1,
  "payment_means_type_code": "10",
  "add_prepaid_amount": false,
  "reason_id": null,
  "notes": [{"language_id": "en", "note": "Docs verification 1791114314"}],
  "form_lines": [
    {
      "item_name": "Consulting",
      "invoiced_quantity": 1,
      "invoiced_quantity_unit_of_measure": "PCE",
      "item_net_price": "100",
      "vat_category_code": "S",
      "vat_rate": 15.0,
      "vat_exemption_reason_code": "",
      "vat_exemption_reason_text": ""
    }
  ],
  "lines": [],
  "original_invoice_reference": [],
  "prepaid_invoices": [],
  "document_level_allowances": []
}
Field Type Rule
device, seller, buyer uuid strings from step 3
type_code int 388 here; 381 credit and 383 debit notes use this same endpoint
transaction_code string 0100000 standard, 0200000 simplified, 0100100 standard export; must suit the device's invoice_type
issue_date, issue_time YYYY-MM-DD, HH:MM:SS set by the server, which discards what you send: this body carried 2026-10-01 and 10:00:00, and the preview came back 2026-10-04 15:39:40, Riyadh time. Required keys on release 0.108.7, optional after it
supply_date, supply_end_date YYYY-MM-DD yours: when the goods or service were delivered
currency, exchange_rate string, number SAR and exactly 1 for a domestic sale
payment_means_type_code string "10" cash; "30" credit transfer also needs payment terms, which come from the reason in reason_id
form_lines[] objects the lines you write; lines stays []. Send one or the other, never both
form_lines[].item_name string 4 to 50 characters
form_lines[].item_net_price string decimal greater than zero, at most two decimals
form_lines[].vat_category_code, vat_rate S/Z/E/O, number every category but S needs both vat_exemption_reason_code and vat_exemption_reason_text
reason_id, original_invoice_reference, prepaid_invoices for credit and debit notes and advance payments; empty here

is_sample_invoice and document_level_charges are not input fields; Clix sets both, and this body leaves them out. What each of these constants means and what else it may be: Codes and constants.

curl -s -X POST "$CLIX_API/api/invoices/preview/" -H "Authorization: Bearer $CLIX_KEY" \
  -H "Content-Type: application/json" -d @invoice.json

201:

{
  "message": "Invoice preview created successfully",
  "invoice": {
    "uuid": "61514d6c-…",
    "ref_num": "161-4",
    "counter": 4,
    "device": "6107f3ee-…",
    "buyer": "a94027ce-…",
    "issue_date": "2026-10-04",
    "issue_time": "15:39:40",
    "invoice_total_amount_without_vat": "100.00",
    "invoice_total_vat_amount": "15.00",
    "invoice_payable_amount": "115.00",
    "is_sample_invoice": false,
    "…": "lines, vat_breakdown, qrcode, complete_invoice_xml, invoice_hash_bytes and the other fields of a full invoice"
  }
}

ref_num is the number the next invoice will take, not a reservation: the simplified invoice created a minute later took 161-4. The preview uuid is not an invoice: GET /api/invoices/61514d6c-…/ answers 404 {"message": "Invoice not found"}.

A preview runs the same validation as a create. Two refusals, both 400, sent as previews of this body with one field changed:

{"message": ["invoice_schema_data: Value error, Missing required fields: device. Optional fields not provided: reason_id"]}
{"message": "Payment terms are required for credit payment."}

The first came from device: null; the second from payment_means_type_code: "30" with no reason_id. Payment terms are the description of the reason named in reason_id; a payment_terms key in the body is ignored.

5. Create

curl -s -X POST "$CLIX_API/api/invoices/" -H "Authorization: Bearer $CLIX_KEY" \
  -H "Content-Type: application/json" -d @invoice.json

202, verbatim but for the task_id:

{
  "message": "Tax Invoice creation request completed successfully, it will be cleared or reported to ZATCA soon",
  "location": "/api/invoices/5722b9f8-…/",
  "task_id": "…"
}

Keep location. task_id has no endpoint.

In the 2026-09-27 run, sending the identical body again inside five minutes answered 400:

{"message": "You just submitted an invoice with the exact same data. Please wait 295 seconds before retrying."}

6. Poll

curl -s "$CLIX_API/api/invoices/5722b9f8-…/" -H "Authorization: Bearer $CLIX_KEY"

200. The response carries every field of the invoice; these are the ones a poller reads:

{
  "uuid": "5722b9f8-…",
  "ref_num": "161-3",
  "issue_date": "2026-10-04",
  "issue_time": "14:45:15",
  "zatca_submitted_at": "2026-10-04T11:45:16.233Z",
  "zatca_response_received_at": "2026-10-04T11:45:16.801Z",
  "zatca_response_status": "CLEARED",
  "zatca_response_code": 200,
  "zatca_response_data": {
    "clearedInvoice": "PD94bWwgdmVyc2lvbj0i…",
    "clearanceStatus": "CLEARED",
    "validationResults": {
      "status": "PASS",
      "infoMessages": [
        {"code": "XSD_ZATCA_VALID", "type": "INFO", "status": "PASS", "category": "XSD validation",
         "message": "Complied with UBL 2.1 standards in line with ZATCA specifications"}
      ],
      "errorMessages": [],
      "warningMessages": []
    }
  },
  "invoice_status": "CLEARED",
  "payment_status": "Pending",
  "invoice_pdf_url": "https://…/300075588700003_20261004T144515_161-3.pdf",
  "qr_code": "…",
  "share_link": null,
  "invoice_total_amount_without_vat": "100.00",
  "invoice_total_vat_amount": "15.00",
  "invoice_payable_amount": "115.00",
  "vat_breakdown": [ { "vat_category_code": "S", "vat_rate": 15.0, "vat_category_taxable_amount": "100.00", "vat_category_tax_amount": "15.00", "vat_exemption_reason_code": "", "vat_exemption_reason_text": "" } ],
  "lines": [ { "invoice_line_id": "3fac3c63-…", "item_name": "Consulting", "invoiced_quantity": 1.0, "item_net_price": "100.00", "line_net_amount": "100.00", "vat_line_amount": "15.00", "…": "…" } ],
  "balance": { "paid": "0.00", "credit_notes": "0.00", "debit_notes": "0.00", "debit_notes_paid": "0.00", "remaining": "115.00", "payment_status": "Pending" },
  "buyer": { "uuid": "a94027ce-…", "buyer_name": "Al Noor Trading", "…": "…" },
  "seller": "4d735e52-…",
  "device": "6107f3ee-…"
}
Field Meaning
zatca_response_status CLEARED, REPORTED, NOT_CLEARED, NOT_REPORTED; stop polling on any of them. No response means ZATCA gave no answer Clix recognises; the invoice is still undecided
zatca_response_code ZATCA's HTTP status; 200 accepted, 202 accepted with warnings, 400 rejected
zatca_response_data.validationResults.errorMessages[] why it was rejected, each with code, category, message; warningMessages[] are accepted-with-warnings; infoMessages[] are the checks that passed
zatca_response_data.clearedInvoice the signed XML, base64, on a cleared invoice; null on rejection
invoice_pdf_url set once the invoice is final
payment_status Pending, Partially Paid, Paid; moved by the payments you record, not by ZATCA
lines[].invoice_line_id the line a credit or debit note points at
buyer, seller, device buyer comes back as an object; seller and device as uuid strings

ZATCA answered 0.6 seconds after submission. A rejected invoice cannot be resubmitted: PATCH /api/invoices/{invoice_id}/clearance-reporting/ answers 409 once ZATCA has answered, rejection included. Fix the cause and create a new invoice.

With your own VAT number on the sandbox, expect NOT_CLEARED

The sandbox signs every invoice with one shared certificate, issued for ZATCA's sample VAT number. An organisation with any other VAT number gets NOT_CLEARED, zatca_response_code 400, and this error. The 2026-09-27 run got it:

{"code": "certificate-permissions",
 "message": "User only allowed to use the vat number that exists in the authentication certificate"}

On app.goclix.ai the same body from an active device clears.

7. PDF

curl -s "$CLIX_API/api/invoices/5722b9f8-…/pdf-a3/" -H "Authorization: Bearer $CLIX_KEY" -o 161-3.pdf

200, with these headers, and 45,389 bytes of PDF that start %PDF-1.7, with the ZATCA XML embedded:

Content-Type: application/pdf
Content-Disposition: attachment; filename="300075588700003_20261004T144515_161-3.pdf"
Content-Length: 45389

Before the invoice is final, and on a rejected invoice, the same call answers 404. The 2026-09-27 run's rejected invoice got:

{"message": "Invoice PDF not found"}

A simplified invoice

A simplified invoice, to a consumer, takes transaction_code "0200000" and no buyer. ZATCA reports it instead of clearing it. The body, simplified.json, exactly as sent; it leaves out issue_date and issue_time, which the server sets:

{
  "device": "6107f3ee-…",
  "seller": "4d735e52-…",
  "type_code": 388,
  "transaction_code": "0200000",
  "supply_date": "2026-10-04",
  "supply_end_date": "2026-10-04",
  "currency": "SAR",
  "exchange_rate": 1,
  "payment_means_type_code": "10",
  "add_prepaid_amount": false,
  "reason_id": null,
  "notes": [{"language_id": "en", "note": "Docs worked example, simplified"}],
  "form_lines": [
    {
      "item_name": "Coffee, large",
      "invoiced_quantity": 2,
      "invoiced_quantity_unit_of_measure": "PCE",
      "item_net_price": "10.00",
      "vat_category_code": "S",
      "vat_rate": 15.0,
      "vat_exemption_reason_code": "",
      "vat_exemption_reason_text": ""
    }
  ],
  "lines": [],
  "original_invoice_reference": [],
  "prepaid_invoices": [],
  "document_level_allowances": []
}
curl -s -X POST "$CLIX_API/api/invoices/" -H "Authorization: Bearer $CLIX_KEY" \
  -H "Content-Type: application/json" -d @simplified.json

202:

{
  "message": "Tax Invoice creation request completed successfully, it will be cleared or reported to ZATCA soon",
  "location": "/api/invoices/75d33fb8-…/",
  "task_id": "…"
}

Ten seconds later, GET /api/invoices/75d33fb8-…/ answered 200:

{
  "uuid": "75d33fb8-…",
  "ref_num": "161-4",
  "transaction_code": "0200000",
  "issue_date": "2026-10-04",
  "issue_time": "15:39:50",
  "zatca_submitted_at": "2026-10-04T12:39:50.873Z",
  "zatca_response_received_at": "2026-10-04T12:39:51.413Z",
  "zatca_response_status": "REPORTED",
  "zatca_response_code": 202,
  "zatca_response_data": {
    "reportingStatus": "REPORTED",
    "validationResults": {
      "status": "WARNING",
      "infoMessages": [
        {"code": "XSD_ZATCA_VALID", "type": "INFO", "status": "PASS", "category": "XSD validation",
         "message": "Complied with UBL 2.1 standards in line with ZATCA specifications"}
      ],
      "errorMessages": [],
      "warningMessages": [
        {"code": "certificate-issuer-name", "type": "WARNING", "status": "WARNING", "category": "CERTIFICATE_ERRORS",
         "message": "X509Certificate (CCSID / PCSID) used for signing is not valid certificate (CCSID / PCSID) for this VAT Registration Number."},
        {"code": "invalid-signing-certificate", "type": "WARNING", "status": "WARNING", "category": "CERTIFICATE_ERRORS",
         "message": "X509Certificate (CCSID / PCSID) used for signing is not valid certificate (CCSID / PCSID) for this VAT Registration Number."}
      ]
    }
  },
  "invoice_status": "REPORTED",
  "invoice_pdf_url": "https://…/300075588700003_20261004T153950_161-4.pdf",
  "invoice_total_amount_without_vat": "20.00",
  "invoice_total_vat_amount": "3.00",
  "invoice_payable_amount": "23.00",
  "buyer": "",
  "share_link": null,
  "…": "lines, vat_breakdown, balance and the rest, as in step 6"
}

Three differences from the standard invoice:

  • zatca_response_data carries reportingStatus and no clearedInvoice. ZATCA reports a simplified invoice; it does not return a signed copy.
  • zatca_response_code 202 with status WARNING: ZATCA accepted the invoice with two warnings, both about the signing certificate. REPORTED is final; the warnings need no action on this invoice.
  • buyer is an empty string, not null and not an object.

invoices_used in GET /api/usage/current/ went from 3 to 4.

A credit note

A credit note is a POST /api/invoices/ with type_code 381, the original's uuid in original_invoice_reference, the original line's invoice_line_id on each line, and a reason_id. The note keeps the original's buyer, device, currency and transaction code.

First, the reason:

curl -s "$CLIX_API/api/sellers/reasons/?is_active=true" -H "Authorization: Bearer $CLIX_KEY"
{
  "reasons": [
    {"uuid": "d95793fa-…", "description": "Additional charge after the original invoice",
     "reason_type": {"code": 383, "value": "DEBIT_NOTE"}, "is_active": true},
    {"uuid": "c4846817-…", "description": "Goods returned by the customer",
     "reason_type": {"code": 381, "value": "CREDIT_NOTE"}, "is_active": true}
  ],
  "total": 2, "num_pages": 1, "current_page": 1
}

Take the row whose reason_type.code is 381. Then the note, against 161-3:

{
  "device": "6107f3ee-…",
  "seller": "4d735e52-…",
  "buyer": "a94027ce-…",
  "type_code": 381,
  "transaction_code": "0100000",
  "supply_date": "2026-10-04",
  "supply_end_date": "2026-10-04",
  "currency": "SAR",
  "exchange_rate": 1,
  "payment_means_type_code": "10",
  "add_prepaid_amount": false,
  "reason_id": "c4846817-…",
  "notes": [{"language_id": "en", "note": "Docs worked example, credit note"}],
  "form_lines": [
    {
      "item_name": "Consulting",
      "invoiced_quantity": 1,
      "invoiced_quantity_unit_of_measure": "PCE",
      "item_net_price": "100.00",
      "vat_category_code": "S",
      "vat_rate": 15.0,
      "vat_exemption_reason_code": "",
      "vat_exemption_reason_text": "",
      "invoice_line_id": "3fac3c63-…"
    }
  ],
  "lines": [],
  "original_invoice_reference": ["5722b9f8-…"],
  "prepaid_invoices": [],
  "document_level_allowances": []
}

POST /api/invoices/ answered 202:

{
  "message": "Credit Note creation request completed successfully, it will be cleared or reported to ZATCA soon",
  "location": "/api/invoices/4a20bee8-…/",
  "task_id": "…"
}

The first poll, a second later:

{
  "ref_num": "161-5",
  "type_code": 381,
  "payment_terms": "Goods returned by the customer",
  "lines": [
    {"invoice_line_id": "4bca88e7-…", "original_invoice_line_id": "3fac3c63-…",
     "item_name": "Consulting", "invoiced_quantity": 1.0,
     "item_net_price": "100.00", "line_net_amount": "100.00", "vat_line_amount": "15.00"}
  ],
  "invoice_total_line_net_amount": "100.00",
  "invoice_total_vat_amount": "15.00",
  "invoice_payable_amount": "115.00",
  "original_invoices": [{"ref_num": "161-3", "type_code": 388, "zatca_response_status": "CLEARED", "…": "…"}],
  "zatca_response_code": 200,
  "zatca_response_status": "CLEARED",
  "zatca_response_data": {"clearedInvoice": "PD94bWwg…", "clearanceStatus": "CLEARED",
    "validationResults": {"status": "PASS", "errorMessages": [], "warningMessages": []}}
}

A credit note line credits at most the original price

This run is a return: item_net_price equals the original line's 100.00. Send a lower price, above 0, and the line is a price correction: it credits invoiced_quantity × that price, the amount off per unit. Send the original line's vat_category_code and vat_rate. item_name and the unit of measure are copied from the original line, whatever you send.

Three limits, each a 400, checked to 2 decimals. Previews on the sandbox on 2026-10-05 answered:

  • A price above the original (120.00 against 100.00):

    {"message": "A credit note line cannot credit more per unit than the original price (sent 120.00, original 100.00). Use a debit note to raise a price."}
    
  • A different VAT category or rate (vat_rate 5 against 15):

    {"message": "A credit note line keeps the original line's VAT. Differs from the original: VAT (sent S 5.00, original S 15.00)."}
    
  • More money than is left on the original line. Returns and corrections on a line together may not exceed its value. After a 30.00 correction on 161-8 (1 × 100.00), a full return is refused when you create it:

    {"message": "Amount for line <invoice_line_id> exceeds what is left to credit. Line value: 100.00, Already credited: 30.00, Left to credit: 70.00, Requested: 100.00."}
    

    The preview does not check this limit; POST /api/invoices/ does.

A correction uses up no quantity: the units can still be returned, up to the money left. It takes no share of the original's document discount. A debit note is different: it keeps the price you send (a preview of a 50.00 debit note against the same line came back 50.00).

On the demo organisation, 161-9 took 30.00 off 161-8's line (payable 34.50, CLEARED), and 161-10 took the remaining 70.00 (payable 80.50, CLEARED).

payment_terms carries the reason's description; that is the reason ZATCA reads. Without a reason_id, Clix refuses the note before it reaches ZATCA:

{"message": "Reason for issuance of credit / debit note as per the VAT Implementing Regulation is missing"}

A note line without invoice_line_id is refused too, for credit and debit notes alike:

{"message": ["invoice_schema_data: Value error, For CN/DN, 'invoice_line_id' is required in each line."]}

Where each field comes from:

Field Source
reason_id uuid of an active row in GET /api/sellers/reasons/?is_active=true whose reason_type.code is 381 (383 for a debit note). An Admin sets reasons up under Invoices → Adjust Reasons; see Credit and debit notes
original_invoice_reference ["<uuid of the cleared or reported invoice>"], from its location
form_lines[].invoice_line_id lines[].invoice_line_id of that invoice, from step 6. A line of any other invoice answers 400 "Referenced invoice line … does not exist in the original invoices."
form_lines[].invoiced_quantity on a credit note, the units to return, or the units a price correction covers. A correction uses up no quantity
form_lines[].item_net_price on a credit note, above 0 and at most the original line's price: equal for a return, lower for a price correction (the amount off per unit); on a debit note, the extra amount per unit
form_lines[].vat_category_code, vat_rate on a credit note, exactly the original line's values; on a debit note, the VAT of the extra amount

8. Revoke

From the 2026-09-27 run, with a throwaway key. Nothing was revoked on 2026-10-04.

In the app, API Keys, Revoke on the row, Revoke key in the Revoke this key? dialog. The very next call answered:

{"status": "false", "message": "Invalid or revoked API key"}

with status 401, within a second of the click.

What was not run

A created debit note (type_code 383; only previewed, see A credit note), invoice comments (POST /api/invoices/{invoice_id}/notes/), client creation (POST /api/onboarding/organizations/clients/), item creation (POST /api/items/) and resubmission (PATCH …/clearance-reporting/) are on the surface and in Swagger but were not exercised in this run. Their schemas are in the OpenAPI document above.