Skip to content

Common API tasks

The calls below cover the jobs integrations do most. Each example uses the clientfence() helper from the API overview (PHP) and the admin role. Every call and all its parameters are in the API reference.

client/create needs email and first_name, and returns the new client’s id. By default the client gets a welcome email with a link to set a password.

$clientId = clientfence('client/create', [
'email' => 'jane@example.com',
'first_name' => 'Jane',
'last_name' => 'Doe',
'currency' => 'USD',
]);

To find a client first, client/get takes id or email.

order/create needs client_id and product_id. Give period (such as 1M or 1Y) for a recurring product, and invoice_option: issue-invoice to issue the first invoice now. It returns the new order’s id.

$orderId = clientfence('order/create', [
'client_id' => $clientId,
'product_id' => 4,
'period' => '1M',
'invoice_option' => 'issue-invoice',
]);

invoice/prepare makes a draft invoice with your lines; approve: true issues it at once and emails it to the client.

$invoiceId = clientfence('invoice/prepare', [
'client_id' => $clientId,
'items' => [['title' => 'Website migration', 'price' => 50, 'quantity' => 1, 'taxed' => true]],
'approve' => true,
]);

For money received outside a payment gateway, such as a bank transfer, invoice/mark_as_paid records the payment. Give the payment method’s gateway_id and, for a manual method, the payment’s reference as transactionId. An amount less than the balance due records a part payment and the invoice stays unpaid.

clientfence('invoice/mark_as_paid', [
'id' => $invoiceId,
'gateway_id' => 3,
'transactionId' => 'BANK-2026-1117',
]);

To list what is still owed, call invoice/get_list with status: unpaid (and client_id for one client).

order/suspend suspends an active order and its add-ons, on the hosting server too; the client sees the reason, and skip_event: true sends no email. order/unsuspend turns it back on.

clientfence('order/suspend', ['id' => $orderId, 'reason' => 'Abuse report']);
clientfence('order/unsuspend', ['id' => $orderId]);

support/ticket_create needs client_id, support_helpdesk_id, subject and content. The client gets an email, and the call returns the ticket’s id.

$ticketId = clientfence('support/ticket_create', [
'client_id' => $clientId,
'support_helpdesk_id' => 1,
'subject' => 'Planned server move',
'content' => "Hello Jane,\n\nWe will move your site on Monday.",
]);

To act when something happens in ClientFence (an invoice paid, an order activated), a module can listen to events rather than asking the API again and again.