Wafeq – Gotchas

Wafeq does not separate customers and suppliers as distinct API resources — both share `/v1/contacts/`. The unified `customers` resource sends `relationship[]=customer` to filter, and `suppliers` sends `relationship[]=supplier`. However, Wafeq's `relationship` field is internal and is NOT settable via the API on contact create/update — it is populated by Wafeq based on UI classification or transaction history. Newly-created contacts and contacts with no transactions will appear in BOTH the customers and suppliers lists until Wafeq tags them. To enforce strict customer/supplier separation, manage contact classification in the Wafeq UI.

Wafeq splits payment allocations by document type into separate vendor fields: `accounts_receivable` payments populate `invoice_payments[]`, `accounts_payable` payments populate `bill_payments[]`. Wafeq requires `amount_to_pcy` (amount in primary currency) on each allocation; Apideck mirrors `amount` for single-currency cases. The target invoice or bill must be finalized before a payment can attach — drafts return `403 payment_locked`. To finalize, PATCH the document with the appropriate non-draft status (invoices/credit-notes accept `FINALIZED` or `SENT`, bills accept `AUTHORIZED`); these map to the unified `authorised` status. The bank account's currency must match the payment currency (Wafeq does not auto-convert).

Wafeq does not separate customers and suppliers as distinct API resources — both share `/v1/contacts/`. The unified `suppliers` resource sends `relationship[]=supplier` to filter. However, Wafeq's `relationship` field is internal and is NOT settable via the API on contact create/update — it is populated by Wafeq based on UI classification or transaction history. Newly-created contacts and contacts with no transactions will appear in BOTH the customers and suppliers lists until Wafeq tags them. To enforce strict customer/supplier separation, manage contact classification in the Wafeq UI.