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.