' . AcmeBanner::text() . '
';
});
```
### Pitfalls
> **The HTML you return is not escaped**
>
> These points take **raw HTML**. Embedding a value straight from the customer, the address bar or the database injects code into the site. **Escape** every outside piece yourself; the hook will not do it for you.
> **Your own theme has to carry the hooks**
>
> The hooks live inside theme templates. The three shipped themes carry the same calls, and **a theme you write from scratch** carries only the points you put in it. An add-on not showing on the site is often a missing **theme** point rather than a missing hook.
> **The spot you pick can break the layout**
>
> One point sits inside a box and another outside it. Dropping a full-width block into a grid shifts the page. The last part of the name says where it falls, and the way to be sure is **opening the template at that line**; the hook's entry gives the file and the line.
> **An empty return is the clean way out**
>
> Return `null` where you have nothing to add: empty returns are skipped and leave no trace. Returning an empty `` instead opens a real gap in the grid.
### Related Articles
- [Customer Site Data and Gates](https://dev.wisecp.com/en/customer-site-data-and-gates)
- [Hooks in the Management Panel](https://dev.wisecp.com/en/hooks-in-the-management-panel)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
## Customer Site Data and Gates
https://dev.wisecp.com/en/customer-site-data-and-gates
The customer site away from the screen. 41 filters change data, 10 gates stop an action, and 30 hooks report an event.
### Overview
Screen hooks add HTML. The hooks here touch the data deciding **what a page shows**, stop an action, or report what happened.
Telling the three apart decides where your work goes. Adding a row to a list is a filter. Stopping a spam comment is a gate. Telling an outside system is an event hook.
### Reference
#### The ones that change data
The most used of the forty-one filters. Most hand the value over **by reference**, and the *Ref* column of an entry says which one you can change.
- **filter:client.page.output**: The finished output of a page — the widest place to step in. Changed in place by reference; the return is not used.
- **filter:client.menu**: The site menu tree. Changed by reference; the return is not used.
- **filter:client.breadcrumb**: The breadcrumb trail. Changed by reference; the return is not used.
- **filter:client.dashboard.panels**: The panels on the account dashboard. Changed by reference; the return is not used.
- **filter:client.dashboard.alerts**: The alert strips on the dashboard. Changed by reference; the return is not used.
- **filter:client.list.rows**: List rows — services, invoices, domains. Changed by reference; the return is not used.
- **filter:client.service_detail.data**: The data behind a service detail. Changed by reference; the return is not used.
- **filter:client.domain_detail.data**: The data behind a domain detail. Changed by reference; the return is not used.
- **filter:client.invoice_view_data**: The data behind an invoice view. Changed by reference; the return is not used.
- **filter:client.payment_methods**: The payment methods offered to the customer. Changed by reference; the return is not used.
- **filter:client.theme**: The theme in use. Changed by reference; the return is not used.
- **filter:client.routes**: The site routes. Changed by reference; the return is not used.
#### The ones that stop
Ten gates. They share one contract: returning a non-empty string stops the action, and that text reaches the customer as the error.
- **gate:client.page_access**: Access to a page. A filled return cuts the request off; a listener that redirects must end the request itself.
- **gate:client.contact_submit**: Saving a contact form message. The first filled return vetoes the save.
- **gate:client.blog_comment**: Saving a blog comment. The first filled return vetoes the save.
- **gate:client.api_key_create**: The customer opening a new API key. A filled return stops it.
#### The ones that report
Most of the thirty event hooks report what the customer did on their account. Opening a key, writing a comment, sending a form.
- **action:client.api_key_created**: The customer opened a new API key. The return is ignored.
- **action:client.api_key_revoked**: A key was revoked. The return is ignored.
- **action:client.blog_comment_added**: A blog comment was saved. The return is ignored.
- **action:client.data_prepared**: The page data is ready and drawing is about to start. The return is ignored; add data with `addData()`.
#### The three contracts side by side
```php
// A FILTER: add your own panel to the dashboard (by reference)
Hook::add('filter:client.dashboard.panels', 10, function (&$panels) {
$panels[] = ['title' => 'Acme', 'body' => AcmePanel::html()];
});
// A GATE: stop the comment where the spam score is high
Hook::add('gate:client.blog_comment', 10,
function ($owner_id, $parent_id, $message) {
if (Spam::score($message) > 80) return 'Your comment was not saved.';
return null;
});
// AN EVENT: write the opened key to the audit trail
Hook::add('action:client.api_key_created', 10, function ($owner_id, $new_id, $perms) {
Audit::keyOpened($owner_id, $new_id, $perms);
});
```
### Pitfalls
> **The owner comes from the hook, not the session**
>
> Most customer hooks hand you the **account id** in the first parameter. Use it. Reading from the session brings the wrong person on sub-account and account-switch flows. On a call arriving through the API there is **no session at all**.
> **A gate is not the only defence**
>
> A gate runs on **that flow** alone. Where the same work can be done through the API, that path may not pass this gate. To hold a rule everywhere, check from the hook's entry which call paths the gate covers.
> **The page-output hook runs on every request**
>
> The filter touching a page's finished output runs on **every page view**. A heavy query or an outside call inside it is paid for by the whole site. Cache the heavy work and use only the ready answer in the listener.
### Related Articles
- [Hooks on the Customer Site](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
## Blog and Comment Hooks
https://dev.wisecp.com/en/client-blog-hooks
The seven hooks over blog comments: moderation, editing, deletion, votes and the list.
### Overview
The path of a blog comment lives here: it is written, filtered, listed, moderated and if need be deleted.
Two distinctions to hold from the start. **On a guest comment the author id is zero.** And the moderation gate hands you the **request** while the event hands you the **result**: because pinning is a toggle, the two are not the same.
### Reference
#### Stopping a comment moderation
gateclient.blog_comment_moderate
`ClientBlog` the request, not the result
Runs before a comment is moderated.
Parameters 5
$cidintThe comment id.
$actionstringThe operation **requested**: approve, spam or pin. ? Pinning is a **toggle** request: whether it ends as pinning or unpinning depends on the current state. This value states the request, not the result.
$actor_idintThe id of the administrator doing it.
$author_idintThe author of the comment. It is **zero** on a guest comment: test before doing anything tied to a member.
$owner_idintThe article the comment belongs to.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:client.blog_comment_moderate', 10,
function ($cid, $action, $actor_id, $author_id, $owner_id) {
// 'pin' is a TOGGLE request: you cannot tell the result from here.
if ($action === 'spam' && Acme::protectedAuthor($author_id))
return 'Comments from this author cannot be marked as spam.';
return null;
});
```
#### Following a comment moderation
actionclient.blog_comment_moderated
`ClientBlog` the result, not the request
Runs after the moderation is applied. Unlike the gate, the value here is the operation that **actually happened**.
Parameters 5
$cidintThe comment id.
$actionstringThe operation that **happened**: approved, spam, pinned or unpinned. Against the three values in the gate there are **four** here: the toggle request has split into two separate results.
$actor_idintThe administrator who did it.
$author_idintThe author of the comment. It is **zero** on a guest comment: test before doing anything tied to a member.
$owner_idintThe article the comment belongs to.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.blog_comment_moderated', 10,
function ($cid, $action, $actor_id, $author_id, $owner_id) {
// FOUR values here: the toggle has split in two.
if ($action === 'approved' && $author_id) Acme::thankAuthor($author_id);
});
```
#### Following a comment being edited
actionclient.blog_comment_edited
`ClientBlog` the body is encoded
Runs after a comment is edited by an administrator.
Parameters 5
$cidintThe comment id.
$actor_idintThe administrator who edited it.
$author_idintThe author of the comment. It is **zero** on a guest comment: test before doing anything tied to a member.
$oldstringThe body before the edit. Both arrive **encoded**: showing them directly turns markup into visible text.
$newstringThe body after the edit, as saved.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.blog_comment_edited', 10,
function ($cid, $actor_id, $author_id, $old, $new) {
// Both bodies arrive ENCODED.
Acme::auditEdit($cid, $actor_id, html_entity_decode($old), html_entity_decode($new));
});
```
#### Following a comment being deleted
actionclient.blog_comment_deleted
`ClientBlog` the replies go too
Runs after a comment is deleted.
Parameters 5
$cidintThe id of the deleted comment; the record is gone.
$actor_idintThe administrator who deleted it.
$author_idintThe author of the comment. It is **zero** on a guest comment: test before doing anything tied to a member.
$owner_idintThe article the comment belongs to.
$parent_idintThe comment replied to. ? **A zero means a root comment** went, **and its replies went with it** — with no separate call for them. Clear the whole branch in your own store.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.blog_comment_deleted', 10,
function ($cid, $actor_id, $author_id, $owner_id, $parent_id) {
// On a root comment the replies went too, with no separate call.
if ($parent_id === 0) Acme::dropBranch($cid);
else Acme::dropComment($cid);
});
```
#### Following a comment vote
actionclient.blog_comment_voted
`ClientBlog` a toggle
Runs when a comment is marked helpful or the mark is taken back.
Parameters 4
$cidintThe comment voted on.
$viewer_idintThe member voting. This flow is members only, so the value is **always filled**.
$activeboolThe direction: true for a vote, false for taking it back.
$countintThe current total after the vote.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.blog_comment_voted', 10,
function ($cid, $viewer_id, $active, $count) {
if ($active && $count >= 10) Acme::promoteComment($cid);
});
```
#### Changing a comment body before it is saved
filterclient.blog_comment_message
`ClientBlog` raw text
Runs before a comment is saved. The place to put a filter of your own.
Parameters 2
$messagestringby linkThe comment body, **raw** and not yet encoded. What you write over it is saved.
$ctxarrayby linkContext: the article, the comment replied to, the member id and whether it is a guest. The member id is zero for a guest.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.blog_comment_message', 10, function (&$message, &$ctx) {
// The body is RAW: encoding happens afterwards.
$message = Acme::stripLinks($message);
});
```
#### Changing the comment list
filterclient.blog_comment_list
`ClientBlog` an admin sees more
Runs before the comments reach the screen. It runs separately for reply lists too.
Parameters 2
$itemsarrayby linkThe comments to show, with their formatted fields.
$ctxarrayby linkContext: whether this is a reply list, which article, and whether an administrator is looking. ? **When an administrator looks, comments awaiting approval are in the list too.** A listener ignoring that counts or exports unpublished content.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.blog_comment_list', 10, function (&$items, &$ctx) {
// When an administrator looks, pending comments are in the list too.
if ($ctx['is_admin'] ?? false) return;
$items = Acme::hideFlagged($items);
});
```
### Pitfalls
> **The gate states the request, the event the result**
>
> In the moderation gate pinning is a **toggle** request: you cannot tell from there whether it ends as pinning or unpinning. In the event the value arrives already split in two. A rule assuming the result at the gate misjudges an unpinning.
> **Deleting a root comment takes its replies**
>
> A zero parent id in the delete event means a **root comment** went and every reply beneath it went too. But **no separate call arrives** for those replies: you must clear the whole branch on your side, or orphan records remain.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Knowledge Base Display Hooks](https://dev.wisecp.com/en/knowledge-base-display-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Site Content Hooks
https://dev.wisecp.com/en/client-content-hooks
The twelve hooks over pages, news, slides, testimonials and the menu.
### Overview
The written content of the site lives here: pages, contracts, news, articles, references, slides, testimonials and the menu.
The save path splits into two filters: the **main record** passes once, the **language data** once per language. If you clean the body, the second is the right place.
### Reference
#### Stopping content being deleted
gateclient.content_delete
`ClientContent` five content types
Runs before a piece of site content is deleted. Pages, contracts, news, articles and references share this gate.
Parameters 2
$pagearrayThe record about to be deleted.
$page_typestringThe content type. Deleting a contract can affect the order flow tied to it: be stricter for some types.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:client.content_delete', 10, function ($page, $page_type) {
// Deleting a contract can affect the order flow.
if ($page_type === 'contract') return 'Contracts cannot be deleted; switch them off instead.';
return null;
});
```
#### Following content being deleted
actionclient.content.deleted
`ClientContent` after deletion
Runs after a piece of site content is deleted.
Parameters 3
$idintThe id of the deleted record.
$page_typestringThe content type.
$pagearrayThe record as read before deletion.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.content.deleted', 10, function ($id, $page_type, $page) {
Acme::dropFromIndex('page', $id);
});
```
#### Following content being viewed
actionclient.content.viewed
`ClientContent` on every visit
Runs when a piece of site content is visited. The visitor may not be logged in.
Parameters 3
$idintThe id of the record viewed.
$typestringThe content type.
$recordarrayThe record data, with the visit counter already increased. Its shape follows the type: a blog record carries a category, a plain page does not.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.content.viewed', 10, function ($id, $type, $record) {
// It runs on every visit: keep it light.
Acme::trackView($type, $id);
});
```
#### Changing the content detail data
filterclient.content_detail.data
`ClientContent` passed by link
Runs before the content reaches the screen. The place to resolve your own shortcodes or adjust the search headings.
Parameters 3
$recordarrayby linkThe record data: title, body, link and search headings.
$idintby linkThe record id.
$typestringby linkThe content type.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.content_detail.data', 10, function (&$record, &$id, &$type) {
if ($type !== 'articles') return;
$record['content'] = Acme::resolveShortcodes($record['content'] ?? '');
});
```
#### Changing the content data before it is saved
filterclient.content_save_data
`ClientContent` options are text
Runs before the main record of a piece of content is written.
Parameters 3
$set_dataarrayby linkThe data to be written. ? The options field is **text**, not an array: to change it you must decode, edit and encode again. Writing to it as an array corrupts the record.
$page_typestringThe content type.
$idintThe record id; **zero on a new record**.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.content_save_data', 10, function (&$set_data, $page_type, $id) {
// The options are TEXT: decode, edit, encode again.
$opt = Utility::jdecode($set_data['options'] ?? '', true) ?: [];
$opt['acme_reviewed'] = 1;
$set_data['options'] = Utility::jencode($opt);
});
```
#### Changing the language data before it is saved
filterclient.content_lang_data
`ClientContent` per language
Runs separately for each language of the content. The body is raw markup, which makes this the right place to clean it.
Parameters 3
$set_lang_dataarrayby linkThe data of that language: title, address, body and search headings. Leave the address empty and it falls back to the record id.
$lkeystringThe language key.
$page_typestringThe content type.
Return 1
voidThe return is ignored; you write over the data. The hook runs once per language: on a two-language record you are called twice.
Listener PHP
```php
Hook::add('filter:client.content_lang_data', 10,
function (&$set_lang_data, $lkey, $page_type) {
// The body is raw markup: this is the right place to clean it.
$set_lang_data['content'] = Acme::sanitize($set_lang_data['content'] ?? '');
});
```
#### Following a page being saved
actionclient.page_saved
`ClientContent` create and edit
Runs after a page is saved.
Parameters 3
$idintThe record id; on a new record the real id is passed.
$page_typestringThe page type.
$is_newboolTrue when newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.page_saved', 10, function ($id, $page_type, $is_new) {
Acme::reindex('page', $id);
});
```
#### Following a blog record being saved
actionclient.blog.saved
`ClientContent` create and edit
Runs after a blog record is saved.
Parameters 2
$idintThe record id; on a new record the real id is passed.
$is_newboolTrue when newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.blog.saved', 10, function ($id, $is_new) {
Acme::reindex('page', $id);
});
```
#### Following a news item being saved
actionclient.news.saved
`ClientContent` create and edit
Runs after a news item is saved.
Parameters 2
$idintThe record id; on a new record the real id is passed.
$is_newboolTrue when newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.news.saved', 10, function ($id, $is_new) {
Acme::reindex('page', $id);
});
```
#### Following a slide being saved
actionclient.slide.saved
`ClientContent` create and edit
Runs after a slide is saved.
Parameters 2
$idintThe record id; on a new record the real id is passed.
$is_newboolTrue when newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.slide.saved', 10, function ($id, $is_new) {
Acme::reindex('page', $id);
});
```
#### Following a testimonial being saved
actionclient.feedback.saved
`ClientContent` the approval state
Runs after a customer testimonial on the site is saved.
Parameters 3
$idintThe testimonial id.
$statusstringIts state: approved or awaiting approval. One awaiting approval **does not appear** on the site: check before doing anything tied to publication.
$is_newboolTrue when newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.feedback.saved', 10, function ($id, $status, $is_new) {
// One awaiting approval does not appear on the site.
if ($status === 'approved') Acme::publishTestimonial($id);
});
```
#### Changing menu edits before they are saved
filterclient.menu_save_changes
`ClientContent` a batch of operations
Runs before changes to the site menu are applied.
Parameters 1
$changesarrayby linkThe changes to apply. It is not one record but a **batch**: each entry carries an operation type and its data. Adding, editing, deleting and reordering can sit together in one request.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.menu_save_changes', 10, function (&$changes) {
// A batch: adding, editing, deleting and reordering can sit together.
$changes = array_values(array_filter($changes,
fn ($c) => ($c['type'] ?? '') !== 'delete' || Acme::menuDeletable($c['data'] ?? [])));
});
```
### Pitfalls
> **The options field is text, not an array**
>
> In the content save filter the options field arrives as **encoded text**. Writing a key into it as though it were an array corrupts the field and leaves the record unreadable. The fix: decode, edit, encode again.
> **The language filter runs once per language**
>
> The language data filter is called **per language**: three times on a three-language record. A listener keeping a counter or doing one-off work runs three times here. Use the main record filter for anything that should happen once.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Knowledge Base Display Hooks](https://dev.wisecp.com/en/knowledge-base-display-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Customer Account and Contact Hooks
https://dev.wisecp.com/en/client-account-and-contact-hooks
The fourteen hooks over the customer account and site contact: API keys, the profile, currency, the contact form and the newsletter.
### Overview
The traces a customer or visitor leaves on the site live here: API keys, the profile, the currency preference, the contact form and the newsletter.
In most of these hooks the data comes from an **unverified source**: the visitor filling in the contact form, the address signing up, the bot requesting a page that does not exist. Check it yourself before carrying it to an outside service.
### Reference
#### Following API key permissions changing
actionclient.api_key_updated
`AccountApiKeys` the new permissions only
Runs after the permissions of an API key change. A widening of permissions is a security event.
Parameters 3
$owner_idintThe owner of the key.
$idintThe id of the key record.
$permsarrayThe **new** permission set. ? The old set is not passed: to answer "did permissions widen" you must have **kept the previous state yourself**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.api_key_updated', 10, function ($owner_id, $id, $perms) {
// The old set is not passed: keep it yourself to compare.
Acme::recordScopes($id, $perms);
});
```
#### Following an API key being regenerated
actionclient.api_key_regenerated
`AccountApiKeys` the record stays
Runs after the value of an API key is regenerated. **The record stays, the credential changes**: calls made with the old value no longer pass.
Parameters 2
$owner_idintThe owner of the key.
$idintThe record id; it is the same after the regeneration.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.api_key_regenerated', 10, function ($owner_id, $id) {
// The old value no longer passes: refresh your own cache.
Acme::invalidateCachedKey($id);
});
```
#### Following an API key being deleted
actionclient.api_key_deleted
`AccountApiKeys` the record is gone
Runs after an API key is deleted.
Parameters 2
$owner_idintThe owner of the key.
$idintThe id of the deleted record; the row is gone.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.api_key_deleted', 10, function ($owner_id, $id) {
Acme::revokeIntegration($id);
});
```
#### Following a customer profile being updated
actionclient.profile_updated
`AccountProfile` the account, not the login
Runs after a customer profile is updated.
Parameters 3
$uidintThe id of the **account** whose profile changed. ? It is **not** the id of whoever signed in: a sub-user with the right permission can update another account’s profile. If you record the actor, read it from the session separately.
$data_updatesarrayThe fields written to the main record, **new values only**: name, phone, language, currency.
$info_updatesarrayWhat was written to the extra record: customer kind, company details, address fields.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.profile_updated', 10, function ($uid, $data_updates, $info_updates) {
// $uid is the ACCOUNT id, not the login.
Acme::syncCrm($uid, $data_updates + $info_updates);
});
```
#### Following a currency change
actionclient.currency_changed
`website` empty for a guest
Runs when a visitor changes the site currency. The change is **already applied**.
Parameters 3
$new_cidintThe new currency.
$old_cidintThe previous currency.
$memberarrayThe session of the signed-in member. It is **empty for a guest**: this hook runs for visitors who are not signed in too.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.currency_changed', 10, function ($new_cid, $old_cid, $member) {
// For a guest the member data arrives EMPTY.
if (!$member) return;
Acme::rememberCurrency((int) ($member['id'] ?? 0), $new_cid);
});
```
#### Following a page that was not found
actionclient.page_not_found
`website` bot traffic included
Runs when a requested address does not resolve. It is the most direct way to find broken links.
Parameters 1
$urlstringThe full address requested. ? This hook also runs on addresses tried by **scanning bots**, and on a site those can outnumber human traffic. A listener writing a record on every call fills its own table with noise.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.page_not_found', 10, function ($url) {
// Bot traffic can outnumber human traffic: filter it.
if (Acme::looksLikeScanner($url)) return;
Acme::noteBrokenLink($url);
});
```
#### Following a contact form submission
actionclient.contact_submitted
`ClientContact` comes from a visitor
Runs after a visitor submits the contact form.
Parameters 6
$message_idintThe id of the message record created.
$full_namestringThe sender’s name.
$emailstringThe sender’s address.
$phonestringTheir phone; it **can be empty**.
$messagestringThe message body, stripped of markup.
$ipstringTheir network address. All of these **come from a visitor** and none are verified: check them yourself before sending them to an outside service.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.contact_submitted', 10,
function ($message_id, $full_name, $email, $phone, $message, $ip) {
// All of these come FROM A VISITOR and are unverified.
Acme::pushToCrm($message_id, $email, $message);
});
```
#### Following a contact message being answered
actionclient.contact_message_replied
`ClientContact` after the reply
Runs after an administrator answers a contact message.
Parameters 2
$messagearrayThe original message answered.
$admin_messagestringThe reply text sent.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.contact_message_replied', 10, function ($message, $admin_message) {
Acme::closeCrmCase((int) ($message['id'] ?? 0));
});
```
#### Following a message being reported as spam
actionclient.contact_message_spam_reported
`ClientContact` two separate flags
Runs after a contact message is reported as spam. The two flags beside it say **how far the action went**.
Parameters 3
$messagearrayThe message moved to spam, with its address and phone.
$block_emailsintWhether the address and phone went onto the block list.
$report_spamintWhether the network address was blocked. The two flags are independent: one can be set and the other not. A listener treating them as one reports the wrong thing.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.contact_message_spam_reported', 10,
function ($message, $block_emails, $report_spam) {
// The two flags are independent.
if ($report_spam) Acme::shareBadAddress($message['ip'] ?? '');
});
```
#### Stopping a message becoming a ticket
gateclient.contact_message_to_ticket
`ClientContact` before the conversion
Runs before a contact message is turned into a support ticket.
Parameters 3
$messagearrayThe message to be converted.
$departmentintThe target department.
$staffintThe staff member to assign; a **zero** means none.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the visitor as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:client.contact_message_to_ticket', 10,
function ($message, $department, $staff) {
if (Acme::blockedSender($message['email'] ?? '')) return 'No ticket can be opened for this sender.';
return null;
});
```
#### Changing the contact page data
filterclient.contact_page_data
`ClientContact` added keys reach the template
Runs before the contact page is shown. The offices and support hours are already resolved for the active language.
Parameters 2
$page_dataarrayby linkThe page data. Every key you add **becomes a template variable**: you can use it directly in your theme.
$langstringby linkThe active language.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.contact_page_data', 10, function (&$page_data, &$lang) {
// A key you add becomes a template variable.
$page_data['acme_map'] = Acme::mapEmbed($lang);
});
```
#### Stopping a newsletter sign-up
gateclient.newsletter_subscribe
`ClientNewsletter` before the record
Runs before an address joins the newsletter list. The place to keep disposable addresses out.
Parameters 2
$emailstringThe candidate address, lower-cased with its format checked.
$langstringThe site language at the moment of signing up.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the visitor as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:client.newsletter_subscribe', 10, function ($email, $lang) {
if (Acme::disposableDomain($email)) return 'This address is not accepted.';
return null;
});
```
#### Following a newsletter sign-up
actionclient.newsletter_subscribed
`ClientNewsletter` the language is kept too
Runs after an address joins the newsletter list.
Parameters 3
$emailstringThe subscriber address.
$langstringThe language at sign-up. It is kept and **decides the language of bulk mailings**: get it wrong and the subscriber receives an email they cannot read.
$addedintThe id of the record created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.newsletter_subscribed', 10, function ($email, $lang, $added) {
// The language decides the content language of bulk mailings.
Acme::syncMailingList($email, $lang);
});
```
#### Following a newsletter unsubscribe
actionclient.newsletter_unsubscribed
`ClientNewsletter` through a link
Runs after an address leaves the list. It happens through the link in the email, with no sign-in needed.
Parameters 1
$emailstringThe address removed from the list.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.newsletter_unsubscribed', 10, function ($email) {
// Remove it from your own list too, or mailings carry on.
Acme::dropFromMailingList($email);
});
```
### Pitfalls
> **The id in the profile hook is the account id**
>
> The id handed to the update hook belongs to the **account being changed**, not to whoever made the change. A sub-user with the right permission can update another account’s profile. If you record "who did it", read it from the session separately.
> **The not-found hook fills with bot traffic**
>
> Scanning bots try addresses that do not exist all day, and on a site those requests easily outnumber human ones. A listener writing a record on every call inflates its own table and buries the real broken links. Put a filter in front of it.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Account and Contact Hooks](https://dev.wisecp.com/en/account-contact-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Customer Panel Data Hooks
https://dev.wisecp.com/en/client-panel-data-hooks
The fifteen data filters of the customer panel: account tabs, home page panels, invoice lists, and the partner and reseller screens.
### Overview
The filters over the data the customer panel carries to the screen live here: the account tabs, the home page panels, the invoice lists, and the partner and reseller screens.
Two things recur in this group. First the **active account**: when a sub-user looks at another account, the id you hold belongs to that account rather than to whoever signed in. Second, amounts arrive **formatted**: read the raw value separately if you compare.
### Reference
#### Hiding account tabs
filterclient.account.tabs
`ClientAccount` a visibility map
Runs before the tabs of a customer account appear. Closing a tab takes the work behind it out of sight too.
Parameters 3
$tabsarrayby linkTab against visibility: profile, contacts, activity, messages, notifications, security and verification. ? This is **visibility only**: closing a tab does not close the operation behind it. To really block access, use the matching gate as well.
$uidintby linkThe id of the **active account**. It is not the id of whoever signed in: when a sub-user is looking at another account, that account’s id arrives.
$selfboolby linkWhether the active account is the person’s own. A false means a sub-user is looking at another account.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.account.tabs', 10, function (&$tabs, &$uid, &$self) {
// Visibility ONLY: it does not close the operation.
if (!$self) $tabs['security'] = false;
});
```
#### Widening the data that reaches the template
filterclient.predefined_data
`Controllers` on every page
Runs before **every page** of the customer site appears. Every key you add here becomes a template variable.
Parameters 2
$dataarrayby linkThe data bag of the page. ? Overwrite an existing key and **the page loses its own data**. Give your keys a prefix.
$ctxarrayby linkContext: the active route and controller name. The hook runs on every page, so check which one you are on before doing anything heavy.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.predefined_data', 10, function (&$data, &$ctx) {
// It runs on EVERY page: check the route first.
if (($ctx['route'] ?? '') !== 'my-account') return;
$data['acme_banner'] = Acme::accountBanner();
});
```
#### Changing the home page panels
filterclient.homepage_panels
`website/home` four panels
Runs once the panels of the home page are prepared.
Parameters 1
$panelsarrayby linkThe data of four panels: spotlight extensions, product cards, feature blocks and announcements. All four arrive in one array: change it without breaking the shape, since the template expects all four keys.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.homepage_panels', 10, function (&$panels) {
// All four keys must stay.
$panels['product_cards'] = Acme::reorderCards($panels['product_cards'] ?? []);
});
```
#### Changing the maintenance decision
filterclient.maintenance
`Kernel` reads backwards
Runs after the maintenance decision is made and before the page is served. This is how you keep certain addresses out of maintenance.
Parameters 3
$passive_maintenanceboolby linkWhat the core decided. ? It **reads backwards**: true means maintenance is **skipped**, false means the maintenance page is shown. Setting it true because the name sounds right takes the site out of maintenance.
$controllerstringThe name of the requested controller.
$foundAdminboolWhether the request is on the admin address.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.maintenance', 10,
function (&$passive_maintenance, $controller, $foundAdmin) {
// It reads BACKWARDS: true = maintenance is SKIPPED.
if ($controller === 'status') $passive_maintenance = true;
});
```
#### Changing the invoice list rows
filterclient.invoice_list_data
`ClientInvoices` formatted rows
Runs before the customer invoice list reaches the screen.
Parameters 2
$rowsarrayby linkThe invoice rows: number, badge, payment link, amount and due line. The amounts are formatted text: read the invoice separately if you need to compare.
$uidintThe customer whose list is on screen.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.invoice_list_data', 10, function (&$rows, $uid) {
foreach ($rows as $i => $r) $rows[$i]['acme_note'] = Acme::noteFor($r['id'] ?? 0);
});
```
#### Changing the invoice summary
filterclient.invoice_list_summary
`ClientInvoices` tiles and the notice
Runs once the summary above the invoice list is prepared.
Parameters 2
$summaryarrayby linkTwo parts: the summary tiles (all, paid, unpaid, overdue) and the outstanding notice. If you change the numbers, update the notice text too: the two are read from different places and can part ways.
$uidintThe customer whose summary is on screen.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.invoice_list_summary', 10, function (&$summary, $uid) {
// If you change the numbers, update the notice text too.
$summary['outstanding']['show'] = Acme::hideOutstanding($uid) ? false : ($summary['outstanding']['show'] ?? false);
});
```
#### Changing the invoice share address
filterclient.invoice_share_url
`ClientInvoices` access without login
Runs after the address is produced when a customer shares an invoice.
Parameters 3
$shareUrlstringby linkThe share address produced. ? That address **needs no sign-in**: whoever sees it can open the invoice and the payment page. Writing it into your own store copies the access too.
$idintThe invoice id.
$ownerIdintThe owner of the invoice.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.invoice_share_url', 10, function (&$shareUrl, $id, $ownerId) {
// The address needs no sign-in: keep it out of your own store.
$shareUrl = Acme::shorten($shareUrl);
});
```
#### Changing the invoice transaction list
filterclient.invoice_transactions
`ClientInvoices` refunds included
Runs before the payment movements of an invoice reach the screen.
Parameters 3
$rowsarrayby linkThe movement rows: method, reference, date, whether it is a refund, and the amount. Refunds are in this list too: mind the flag when totalling.
$idintThe invoice id.
$invCidintThe currency of the invoice.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.invoice_transactions', 10, function (&$rows, $id, $invCid) {
// Refunds are in this list too.
foreach ($rows as $i => $r)
if ($r['refund'] ?? false) $rows[$i]['method'] = 'Acme refund';
});
```
#### Changing the bulk payment list
filterclient.bulk_pay_rows
`ClientInvoices` the active account
Runs on the screen where a customer pays several invoices together.
Parameters 2
$rowsarrayby linkThe invoice rows that can be paid. An invoice you remove becomes unpayable here: the customer has to pay it separately.
$uidintby linkThe id of the **active account**. It is not the id of whoever signed in: when a sub-user is looking at another account, that account’s id arrives.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.bulk_pay_rows', 10, function (&$rows, &$uid) {
// An invoice you remove becomes unpayable here.
$rows = array_values(array_filter($rows, fn ($r) => !Acme::onHold($r['id'] ?? 0)));
});
```
#### Changing the commission list
filterclient.affiliate_commissions
`ClientAffiliate` three states
Runs before a partner’s commission list reaches the screen.
Parameters 2
$commissionsarrayby linkThe commission rows; each carries a **state**: available, clearing or rejected. Keep the three apart when totalling: adding them all shows the partner money they will never receive.
$commissionsCtxarrayContext: the account id, the partner record and the currency.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.affiliate_commissions', 10,
function (&$commissions, $commissionsCtx) {
// Three states: do not total them all.
$commissions = array_values(array_filter($commissions,
fn ($c) => ($c['flag'] ?? '') !== 'rejected'));
});
```
#### Changing the payout channel list
filterclient.affiliate_gateways
`ClientAffiliate` a list of labels
Runs once the payout channels a partner may pick are prepared.
Parameters 2
$outarrayby linkThe channel **labels**. It is a list of plain text, not ids, and the choice is stored as that text. Changing a label can break the match with older records.
$gatewaysCtxarrayContext: the language the labels were resolved in.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.affiliate_gateways', 10, function (&$out, $gatewaysCtx) {
// Changing a label can break the match with older records.
$out[] = 'Acme Wallet';
});
```
#### Changing the referral destination
filterclient.affiliate_referral_redirect
`ClientAffiliate` invalid codes arrive too
Runs when a visitor clicks a partner link, before the redirect happens.
Parameters 2
$redirectstringby linkThe redirect destination.
$redirectCtxarrayContext: the raw code in the address, the resolved partner and whether the code is valid. ? The hook **runs on an invalid code too**: a listener using the partner id without checking the valid flag works with a zero.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.affiliate_referral_redirect', 10,
function (&$redirect, $redirectCtx) {
// It runs on an invalid code too: check the flag first.
if (!($redirectCtx['valid'] ?? false)) return;
$redirect = Acme::landingFor((int) ($redirectCtx['owner_id'] ?? 0)) ?: $redirect;
});
```
#### Changing the payout request amount
filterclient.affiliate_withdraw_amount
`ClientAffiliate` the partner currency
Runs while a partner requests a payout, before the amount is saved. What you write is what gets recorded.
Parameters 4
$amountfloatby linkThe amount requested.
$uidintThe account requesting.
$cidintThe **partner’s** currency. It is not the currency selected in the store: use this one if you convert.
$amountCtxarrayContext information.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.affiliate_withdraw_amount', 10,
function (&$amount, $uid, $cid, $amountCtx) {
// The currency is the PARTNER'S, not the store's.
$amount = Acme::roundToPayoutStep($amount, $cid);
});
```
#### Changing the reseller statistics
filterclient.reseller_stats
`ClientReseller` worked out from invoices
Runs once the figures on the reseller board are worked out.
Parameters 2
$statsarrayby linkThe reseller figures: total sales, turnover and discounts, each with today’s counterpart.
$statsCtxarrayContext: the account id of the reseller.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.reseller_stats', 10, function (&$stats, $statsCtx) {
$stats['acme_target'] = Acme::monthlyTarget((int) ($statsCtx['uid'] ?? 0));
});
```
#### Changing the reseller tiers
filterclient.reseller_tiers
`ClientReseller` two separate surfaces
Runs once the reseller tier list is prepared. The hook is used on **two separate screens**.
Parameters 2
$tiersarrayby linkThe tier rows.
$tiersCtxarrayContext: which screen and the account id. ? On the programme page the account id is **zero** (the visitor may not be signed in); on the board the reseller’s id arrives. A rule depending on the id must behave differently on the two.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.reseller_tiers', 10, function (&$tiers, $tiersCtx) {
// On the programme page the account id arrives as ZERO.
if (($tiersCtx['scope'] ?? '') === 'program') return;
$tiers = Acme::highlightCurrent($tiers, (int) ($tiersCtx['uid'] ?? 0));
});
```
### Pitfalls
> **The maintenance flag reads backwards**
>
> The value in the maintenance filter answers not "is maintenance on" but **"will maintenance be skipped"**. A listener setting it true because the name sounds right **opens the site to visitors** while you meant it closed. Confirm the direction before changing it.
> **Hiding a tab does not close access**
>
> The account tab filter governs **visibility** only. Closing a tab does not close the operation behind it: somebody who knows the address can still request it directly. Use the matching gate to really block access.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Partner Programme Hooks](https://dev.wisecp.com/en/affiliate-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
## Customer Service and Message Hooks
https://dev.wisecp.com/en/client-service-and-message-hooks
The thirteen hooks over the service detail and bulk messaging: the module panel, add-ons, package changes, the usage chart and sending.
### Overview
What a customer sees on the service detail, and bulk message sending, live here.
The service filters share a pattern around **visibility flags**: hiding a section and emptying it give different outcomes. On the message side everything is counted in **parts**; the recipient count does not give you the cost.
### Reference
#### Changing the module panel
filterclient.service_management_content
`ClientServices` raw markup
Runs before the panel produced by the server module is shown to the customer. It is the only place to touch the output of the remote panel.
Parameters 2
$contentstringby linkThe **raw markup** the module produced. ? That output can carry values from the remote server and is shown **unescaped**. If you add a value from outside, clean it yourself.
$ctxarrayContext: the service record and the panel page requested.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.service_management_content', 10, function (&$content, $ctx) {
// The output is shown UNESCAPED.
if (($ctx['page'] ?? '') !== 'dashboard') return;
$content .= '
Acme
';
});
```
#### Changing the add-on lists
filterclient.service_detail.addons
`ClientServices` two lists
Runs once the add-on lists on the service detail are prepared. **Two separate lists** arrive: the ones owned and the ones on offer.
Parameters 3
$addonsOwnedarrayby linkThe add-ons the service holds, active and pending together.
$addonsAvailablearrayby linkThe add-on offers that can be bought. Removing one from the offers also blocks the purchase: the customer never sees it.
$ctxarrayContext: the service record and the account id.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.service_detail.addons', 10,
function (&$addonsOwned, &$addonsAvailable, $ctx) {
// Removing an offer also blocks the purchase.
$addonsAvailable = array_values(array_filter($addonsAvailable,
fn ($a) => Acme::offerAllowed($a, $ctx['service'] ?? [])));
});
```
#### Changing the package change catalogue
filterclient.service_detail.upgrade_plans
`ClientServices` a visibility flag
Runs once the package upgrade and downgrade options are prepared.
Parameters 2
$updownarrayby linkThe plan catalogue and its state flags: visibility, the plan list and prices. Closing the visibility flag hides the section entirely; emptying the plan list shows an empty section. The two are different outcomes.
$ctxarrayContext: the service record.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.service_detail.upgrade_plans', 10, function (&$updown, $ctx) {
// Hiding and emptying are different outcomes.
if (Acme::locked($ctx['service'] ?? [])) $updown['visible'] = false;
});
```
#### Changing the licence transfer section
filterclient.service_detail.license_transfer
`ClientServices` the fee note included
Runs once the transfer section of a software licence is prepared.
Parameters 2
$ltarrayby linkThe transfer data: visibility, mode, whether a transfer is pending, who pays the fee and the fee note.
$ctxarrayContext: the service record and its type.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.service_detail.license_transfer', 10, function (&$lt, $ctx) {
// Do not show the section at all for a licence that cannot move.
if (Acme::nonTransferable($ctx['service'] ?? [])) $lt['visible'] = false;
});
```
#### Changing the service timeline
filterclient.service_detail.activity
`ClientServices` the timeline
Runs before the history rows of a service reach the screen. The place to put your own events among the core ones.
Parameters 2
$activityarrayby linkThe timeline rows.
$ctxarrayContext: the service id.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.service_detail.activity', 10, function (&$activity, $ctx) {
foreach (Acme::events((int) ($ctx['service_id'] ?? 0)) as $e) $activity[] = $e;
});
```
#### Changing the usage chart
filterclient.service_metric_chart
`ClientServices` null marks a gap
Runs once the data of the usage chart is prepared.
Parameters 2
$chartarrayby linkThe chart data: day labels and per-day values. ? A day with no data arrives as **empty**, not zero: turning those into zeros draws a drop that never happened.
$ctxarrayContext: the service, the metric key and the month being charted.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.service_metric_chart', 10, function (&$chart, $ctx) {
// A day with no data arrives EMPTY: do not turn it into a zero.
$chart['acme_limit'] = Acme::planLimit($ctx['metric'] ?? '');
});
```
#### Stopping a message being sent
gateclient.sms_send
`ClientSms` before sending
Runs before a customer sends messages in bulk. The cost is worked out but **not yet charged**.
Parameters 4
$uidintThe account sending.
$originstringThe sender identity.
$quotearrayThe send summary: recipient count, total and countries.
$sendCtxarrayExtra context: the list, the group and the currency.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the customer as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:client.sms_send', 10, function ($uid, $origin, $quote, $sendCtx) {
// The cost is worked out but NOT yet charged.
if ((int) ($quote['recipients'] ?? 0) > Acme::dailyCap($uid))
return 'This exceeds your daily sending limit.';
return null;
});
```
#### Following messages being sent
actionclient.sms_sent
`ClientSms` what was actually billed
Runs after messages go out in bulk.
Parameters 4
$uidintThe account sending.
$originstringThe sender identity.
$quotearrayThe summary of the send. This is **what was actually billed**: recipient count, part count, length and encoding. A long message takes more parts than recipients, and the charge follows the parts.
$sentCtxarrayContext: the currency, the sender record, the module and the batch reference.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.sms_sent', 10, function ($uid, $origin, $quote, $sentCtx) {
// The charge follows the PARTS, not the recipient count.
Acme::recordUsage($uid, (int) ($quote['total_parts'] ?? 0));
});
```
#### Stopping a sender identity being added
gateclient.sms_sender_add
`ClientSms` format already checked
Runs before a customer adds a new sender identity.
Parameters 2
$uidintThe account asking.
$namestringThe sender name requested. Its format is already checked: at most eleven letters or digits, no spaces. Your check belongs on the **content**, not the format.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the customer as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:client.sms_sender_add', 10, function ($uid, $name) {
// The format is already checked: look at the content.
if (Acme::reservedBrand($name)) return 'This name cannot be used.';
return null;
});
```
#### Following a sender identity being added
actionclient.sms_sender_created
`ClientSms` added, not approved
Runs after a new sender identity is added. **Being added does not mean it can be used**: some countries need a separate application.
Parameters 2
$uidintThe account that added it.
$originarrayA summary of the record created: its id and name.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.sms_sender_created', 10, function ($uid, $origin) {
// Being added does not mean it can be used.
Acme::noteSender($uid, $origin['name'] ?? '');
});
```
#### Following a sender application
actionclient.sms_sender_requested
`ClientSms` a country list
Runs after an application is made to pre-register a sender identity.
Parameters 3
$uidintThe account applying.
$originarrayA summary of the sender identity.
$codesarrayThe country codes applied for. A first application can cover several countries; a resubmission is usually one. It always arrives as a **list**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.sms_sender_requested', 10, function ($uid, $origin, $codes) {
// It always arrives as a list.
foreach ($codes as $iso) Acme::trackApplication($uid, $origin['name'] ?? '', $iso);
});
```
#### Following contacts being imported
actionclient.sms_contacts_imported
`ClientSms` skipped counted separately
Runs after a customer imports a contact list.
Parameters 4
$uidintThe account importing.
$importedintHow many contacts were actually written; **always at least one**.
$skippedintHow many rows were skipped for an invalid name or number. The header row skipped automatically is **not** in this number: do not conflate the two when reporting.
$group_idintThe target group; a **zero** means the contacts were saved without one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:client.sms_contacts_imported', 10,
function ($uid, $imported, $skipped, $group_id) {
// The header row is not counted among the skipped.
if ($skipped > 0) Acme::warnImportQuality($uid, $imported, $skipped);
});
```
#### Changing the country price table
filterclient.sms_rate
`ClientSms` per part
Runs once the country prices shown to the customer are prepared.
Parameters 2
$outarrayby linkCountry against price, with the fee and whether pre-registration is needed. ? The fee is **per part**, not per message: a long message splits into several parts and is charged for each.
$ctxarrayContext: the currency the prices were resolved in.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:client.sms_rate', 10, function (&$out, $ctx) {
// The fee is PER PART.
foreach ($out as $iso => $row)
$out[$iso]['rate'] = Acme::applyMargin((float) ($row['rate'] ?? 0));
});
```
### Pitfalls
> **An empty day on the chart is not a zero**
>
> A day with no data collected arrives **empty** in the usage chart. Turning it into a zero draws a drop that never happened and shows the customer a false picture of their usage. Leave the gap as a gap.
> **Message cost is counted per part**
>
> A long message splits into several parts and **each part is charged**. A calculation treating the recipient count as the cost falls far short on long messages. Use the part count from the send summary.
### Related Articles
- [Service Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- [Customer Panel Data Hooks](https://dev.wisecp.com/en/client-panel-data-hooks)
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
## Customer Domain Screen Hooks
https://dev.wisecp.com/en/client-domain-screen-hooks
The twenty-seven placement points of the domain detail and list.
### Overview
The placement points on the customer domain screens live here: every tab of the detail page, the hero block, the modals and the list.
They are all **parameter-less**: the hook does not tell you which domain is on screen. If you need that context, resolve it from the address or from your own side.
### Reference
#### Below the hero block
uiclient.domain_detail.hero.after
`website/domains/detail` no parameters
Appears immediately below the hero block of the domain detail. It suits a warning specific to an extension.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.hero.after', 10, function () {
return '
Acme
';
});
```
#### The end of the hero actions
uiclient.domain_detail.hero_actions.end
`website/domains/detail` no parameters
Appears at the end of the action buttons in the hero block.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.hero_actions.end', 10, function () {
return '
Acme
';
});
```
#### The end of the tab bar
uiclient.domain_detail.tabs.end
`website/domains/detail` no parameters
Appears at the end of the tab bar on the domain detail. The place to add the label of your own tab.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.tabs.end', 10, function () {
return '
Acme
';
});
```
#### The top of the overview tab
uiclient.domain_detail.overview.top
`website/domains/detail` no parameters
Appears at the very top of the overview tab.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.overview.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the overview tab
uiclient.domain_detail.overview.bottom
`website/domains/detail` no parameters
Appears at the very bottom of the overview tab.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.overview.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the name servers tab
uiclient.domain_detail.nameservers.top
`website/domains/detail` no parameters
Appears above the name server form. It suits a reminder that a wrong setting makes the domain unreachable.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.nameservers.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the name servers tab
uiclient.domain_detail.nameservers.bottom
`website/domains/detail` no parameters
Appears below the name server form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.nameservers.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the DNS tab
uiclient.domain_detail.dns.top
`website/domains/detail` no parameters
Appears above the DNS record table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.dns.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the DNS tab
uiclient.domain_detail.dns.bottom
`website/domains/detail` no parameters
Appears below the DNS record table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.dns.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the contacts tab
uiclient.domain_detail.contacts.top
`website/domains/detail` no parameters
Appears above the domain contact details.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.contacts.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the contacts tab
uiclient.domain_detail.contacts.bottom
`website/domains/detail` no parameters
Appears below the contact details.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.contacts.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the forwarding tab
uiclient.domain_detail.forwarding.top
`website/domains/detail` no parameters
Appears above the address and email forwarding settings.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.forwarding.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the forwarding tab
uiclient.domain_detail.forwarding.bottom
`website/domains/detail` no parameters
Appears below the forwarding settings.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.forwarding.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the transfer tab
uiclient.domain_detail.transfer.top
`website/domains/detail` no parameters
Appears above the transfer section.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.transfer.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the transfer tab
uiclient.domain_detail.transfer.bottom
`website/domains/detail` no parameters
Appears below the transfer section.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.transfer.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the billing tab
uiclient.domain_detail.billing.top
`website/domains/detail` no parameters
Appears above the billing section of the domain.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.billing.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the billing tab
uiclient.domain_detail.billing.bottom
`website/domains/detail` no parameters
Appears below the billing section.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.billing.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the invoice list
uiclient.domain_detail.billing_invoices.before
`website/domains/detail` no parameters
Appears immediately above the list of invoices for the domain.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.billing_invoices.before', 10, function () {
return '
Acme
';
});
```
#### The top of the activity tab
uiclient.domain_detail.activity.top
`website/domains/detail` no parameters
Appears above the domain history.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.activity.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the activity tab
uiclient.domain_detail.activity.bottom
`website/domains/detail` no parameters
Appears below the domain history.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.activity.bottom', 10, function () {
return '
Acme
';
});
```
#### After the protection section
uiclient.domain_detail.protection.after
`website/domains/detail` no parameters
Appears after the privacy and transfer lock settings.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.protection.after', 10, function () {
return '
Acme
';
});
```
#### The end of the modals
uiclient.domain_detail.modals.end
`website/domains/detail` no parameters
Appears at the end of the modals on the page. The right place to add one of your own, since it disturbs no layout.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain_detail.modals.end', 10, function () {
return '
Acme
';
});
```
#### After the attention banner
uiclient.domains_list.attention.after
`website/domains` no parameters
Appears after the attention banner on the domain list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domains_list.attention.after', 10, function () {
return '
Acme
';
});
```
#### After the summary tiles
uiclient.domains_list.tiles.after
`website/domains` no parameters
Appears after the summary tiles above the list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domains_list.tiles.after', 10, function () {
return '
Acme
';
});
```
#### The end of the header actions
uiclient.domains_list.header_actions.end
`website/domains` no parameters
Appears at the end of the action buttons in the list header.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domains_list.header_actions.end', 10, function () {
return '
Acme
';
});
```
#### The end of the toolbar
uiclient.domains_list.toolbar.end
`website/domains` no parameters
Appears at the end of the list toolbar.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domains_list.toolbar.end', 10, function () {
return '
Acme
';
});
```
#### The end of the list modals
uiclient.domains_list.modals.end
`website/domains` no parameters
Appears at the end of the modals on the list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domains_list.modals.end', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **Which domain is on screen is not passed**
>
> None of these points hand you the domain. To show something that depends on it, resolve the id **from the address**. Relying on a "last viewed" value from the session shows the wrong domain’s details to a customer with two tabs open.
> **Put a modal at the modal point**
>
> A listener placing its own modal in the middle of a tab pane disturbs the layout, and the modal disappears when the tab changes. There is a **modal point** for this: there it sits outside the page flow.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Customer Service and Message Hooks](https://dev.wisecp.com/en/client-service-and-message-hooks)
- Domain Hooks
## Customer Service Screen Hooks
https://dev.wisecp.com/en/client-service-screen-hooks
The eighteen placement points of the service detail, list and dashboard.
### Overview
The placement points on the customer service screens live here: the detail tabs, the resource gauges, the quick actions and the dashboards.
Adding a tab takes **two points together**: the label goes on the tab bar and the content at the end of the panes. Using only one leaves half a tab.
### Reference
#### The end of the hero actions
uiclient.service_detail.hero.actions.end
`website/services/detail` no parameters
Appears at the end of the action buttons in the hero block of the service detail.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.hero.actions.end', 10, function () {
return '
Acme
';
});
```
#### The end of the tab bar
uiclient.service_detail.tabs.end
`website/services/detail` no parameters
Appears at the end of the tab bar on the service detail.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.tabs.end', 10, function () {
return '
Acme
';
});
```
#### The end of the tab panes
uiclient.service_detail.panes.end
`website/services/detail` no parameters
Appears at the end of the tab panes. **The content of a tab you added to the bar goes here**: the two are used together.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.panes.end', 10, function () {
return '
Acme
';
});
```
#### Above the overview
uiclient.service_detail.overview.before
`website/services/detail` no parameters
Appears at the very top of the overview tab.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.overview.before', 10, function () {
return '
Acme
';
});
```
#### Below the overview
uiclient.service_detail.overview.after
`website/services/detail` no parameters
Appears at the very bottom of the overview tab.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.overview.after', 10, function () {
return '
Acme
';
});
```
#### After the resource gauges
uiclient.service_detail.overview.gauges.after
`website/services/detail` no parameters
Appears after the disk and traffic gauges. The place to add a resource measure of your own.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.overview.gauges.after', 10, function () {
return '
Acme
';
});
```
#### Above the quick actions
uiclient.service_detail.overview.quick_actions.before
`website/services/detail` no parameters
Appears above the quick action buttons.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.overview.quick_actions.before', 10, function () {
return '
Acme
';
});
```
#### After the quick actions
uiclient.service_detail.overview.quick_actions.after
`website/services/detail` no parameters
Appears after the quick action buttons. It puts an action of your own beside the core ones.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.overview.quick_actions.after', 10, function () {
return '
Acme
';
});
```
#### After the panel link on the overview
uiclient.service_detail.overview.sso.after
`website/services/detail` no parameters
Appears after the remote panel link on the overview.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.overview.sso.after', 10, function () {
return '
Acme
';
});
```
#### The top of the management tab
uiclient.service_detail.management.top
`website/services/detail` no parameters
Appears above the remote panel tools.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.management.top', 10, function () {
return '
Acme
';
});
```
#### After the panel link on the management tab
uiclient.service_detail.management.sso.after
`website/services/detail` no parameters
Appears after the remote panel link on the management tab.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.management.sso.after', 10, function () {
return '
Acme
';
});
```
#### The end of the modals
uiclient.service_detail.modals.end
`website/services/detail` no parameters
Appears at the end of the modals on the page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_detail.modals.end', 10, function () {
return '
Acme
';
});
```
#### The top of the service list
uiclient.services_list.top
`website/services` no parameters
Appears at the very top of the customer service list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.services_list.top', 10, function () {
return '
Acme
';
});
```
#### After the summary tiles
uiclient.services_list.tiles.after
`website/services` no parameters
Appears after the summary tiles above the list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.services_list.tiles.after', 10, function () {
return '
Acme
';
});
```
#### Above the service dashboard
uiclient.service_dashboard.before
`website/services` no parameters
Appears above the service-specific dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_dashboard.before', 10, function () {
return '
Acme
';
});
```
#### Below the service dashboard
uiclient.service_dashboard.after
`website/services` no parameters
Appears below the service-specific dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_dashboard.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the service configuration
uiclient.service_config.bottom
`website/services` no parameters
Appears at the bottom of the service configuration screen.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_config.bottom', 10, function () {
return '
Acme
';
});
```
#### The transfer approval page
uiclient.service_transfer_approve.body
`website/services` no parameters
Appears in the body of the service transfer approval page. That page can open for somebody **not signed in**: whoever approves the transfer may have no account.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.service_transfer_approve.body', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **Adding a tab takes two points**
>
> Put a label on the tab bar and skip the pane point and the customer sees a tab that is **empty when clicked**. Use both, and give them the same identifier.
> **The transfer approval page can open without a sign-in**
>
> Whoever approves a service transfer may hold no account at all. Anything tied to a session **comes out empty** on that page, and showing customer details there opens them to somebody you cannot identify.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Customer Service and Message Hooks](https://dev.wisecp.com/en/client-service-and-message-hooks)
- Domain Hooks
## Customer Cart and Checkout Hooks
https://dev.wisecp.com/en/client-cart-and-checkout-hooks
The twenty-nine placement points from the catalogue to the completed order.
### Overview
The placement points along the customer purchase path live here: the catalogue, the product detail, configuration, the basket, checkout and the completed order.
Everything you add along this path stands **in front of a buying decision**. A slow script at the payment step turns directly into orders that never complete; put tracking code on the completion page.
### Reference
#### Above the plan list
uiclient.catalog.plans.before
`website/products` no parameters
Appears above the plan cards on the catalogue page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.catalog.plans.before', 10, function () {
return '
Acme
';
});
```
#### Below the plan list
uiclient.catalog.plans.after
`website/products` no parameters
Appears below the plan cards.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.catalog.plans.after', 10, function () {
return '
Acme
';
});
```
#### The foot of a plan card
uiclient.plan_card.footer
`website/products` no parameters
Appears at the foot of **every plan card**, separately. The card itself is not passed: you cannot tell which plan it is from here.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.plan_card.footer', 10, function () {
return '
Acme
';
});
```
#### After the product gallery
uiclient.product_detail.gallery.after
`website/products` no parameters
Appears after the image area on the product detail.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.product_detail.gallery.after', 10, function () {
return '
Acme
';
});
```
#### Above the purchase box
uiclient.product_detail.purchase.before
`website/products` no parameters
Appears above the price and the purchase button.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.product_detail.purchase.before', 10, function () {
return '
Acme
';
});
```
#### Below the purchase box
uiclient.product_detail.purchase.after
`website/products` no parameters
Appears below the purchase button. It suits a reassuring note or an extra condition.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.product_detail.purchase.after', 10, function () {
return '
Acme
';
});
```
#### The end of the product tabs
uiclient.product_detail.tabs.end
`website/products` no parameters
Appears at the end of the tab bar on the product detail.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.product_detail.tabs.end', 10, function () {
return '
Acme
';
});
```
#### After the software store grid
uiclient.software_store.grid.after
`website/products` no parameters
Appears after the cards in the software store.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.software_store.grid.after', 10, function () {
return '
Acme
';
});
```
#### After the add-on page
uiclient.addon_page.after
`website/products` no parameters
Appears after the content of the add-on purchase page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.addon_page.after', 10, function () {
return '
Acme
';
});
```
#### After the configuration sections
uiclient.configure.sections.after
`website/cart` no parameters
Appears after the sections in the order configuration step.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.configure.sections.after', 10, function () {
return '
Acme
';
});
```
#### After the configuration add-ons
uiclient.configure.addons.after
`website/cart` no parameters
Appears after the add-on selection in the configuration step.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.configure.addons.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the configuration summary
uiclient.configure.summary.bottom
`website/cart` no parameters
Appears below the price summary in the configuration step.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.configure.summary.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the basket items
uiclient.cart.items.top
`website/cart` no parameters
Appears above the items in the basket.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.cart.items.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the basket summary
uiclient.cart.summary.bottom
`website/cart` no parameters
Appears below the basket total summary.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.cart.summary.bottom', 10, function () {
return '
Acme
';
});
```
#### After the empty basket message
uiclient.cart.empty.after
`website/cart` no parameters
Appears after the message shown when the basket is empty. It runs **only when the basket is empty**, which makes it right for a suggestion area.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.cart.empty.after', 10, function () {
return '
Acme
';
});
```
#### The end of the checkout header
uiclient.checkout.header.end
`website/checkout` no parameters
Appears at the end of the header area in the checkout step.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.header.end', 10, function () {
return '
Acme
';
});
```
#### After the billing details
uiclient.checkout.billing.after
`website/checkout` no parameters
Appears after the billing address section.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.billing.after', 10, function () {
return '
Acme
';
});
```
#### After the payment methods
uiclient.checkout.methods.after
`website/checkout` no parameters
Appears after the payment method choice.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.methods.after', 10, function () {
return '
Acme
';
});
```
#### Above the saved cards
uiclient.checkout.cards.top
`website/checkout` no parameters
Appears above the list of saved cards.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.cards.top', 10, function () {
return '
Acme
';
});
```
#### After the terms box
uiclient.checkout.terms.after
`website/checkout` no parameters
Appears after the terms checkbox. If you add a consent of your own, **you must enforce it yourself**: the core only knows its own box.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.terms.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the checkout summary
uiclient.checkout.summary.bottom
`website/checkout` no parameters
Appears below the total summary in the checkout step.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.summary.bottom', 10, function () {
return '
Acme
';
});
```
#### Before the payment step
uiclient.checkout.payment.before
`website/checkout` no parameters
Appears immediately before the payment begins. It suits a final warning.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.payment.before', 10, function () {
return '
Acme
';
});
```
#### The end of the checkout footer
uiclient.checkout.footer.end
`website/checkout` no parameters
Appears in the footer of the checkout step.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.checkout.footer.end', 10, function () {
return '
Acme
';
});
```
#### The top of the payment page
uiclient.pay.body.top
`website/checkout` no parameters
Appears at the very top of the payment page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.pay.body.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the payment page
uiclient.pay.body.bottom
`website/checkout` no parameters
Appears at the very bottom of the payment page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.pay.body.bottom', 10, function () {
return '
Acme
';
});
```
#### After the card form
uiclient.pay.card.after
`website/checkout` no parameters
Appears after the card details form. This area handles card data: remember that a script you add here can reach those fields.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.pay.card.after', 10, function () {
return '
Acme
';
});
```
#### After the paid notice
uiclient.order_complete.paid.after
`website/checkout` no parameters
Appears after the payment confirmation on the order complete page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.order_complete.paid.after', 10, function () {
return '
Acme
';
});
```
#### The end of the order summary
uiclient.order_complete.paid.details.end
`website/checkout` no parameters
Appears at the end of the summary details of the completed order.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.order_complete.paid.details.end', 10, function () {
return '
Acme
';
});
```
#### The bottom of the complete page
uiclient.order_complete.body.bottom
`website/checkout` no parameters
Appears at the very bottom of the order complete page. The right place for conversion tracking.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.order_complete.body.bottom', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **The core does not enforce a checkbox you add**
>
> Put your own consent box at the terms point and the core **never checks** whether it is ticked: the order completes with the box empty. You must enforce it on your side.
> **Every delay on the payment path is a lost sale**
>
> A script at the payment step that calls an outside service makes the customer wait **before they pay**. Move work like conversion tracking to the order completion page, where waiting costs nothing.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- Order Hooks
- Support Ticket Hooks
## Customer Support Screen Hooks
https://dev.wisecp.com/en/client-support-screen-hooks
The fourteen placement points of the ticket list, form and conversation.
### Overview
The placement points on the customer support screens live here: the list, the new ticket form, the conversation and the reply box.
Two points run **for every row**: each message in the conversation and each ticket in the list. Heavy work in those slows the page noticeably.
### Reference
#### Above the ticket list
uiclient.ticket_list.before
`website/tickets` no parameters
Appears above the customer ticket list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_list.before', 10, function () {
return '
Acme
';
});
```
#### The ticket list actions
uiclient.ticket_list.actions
`website/tickets` no parameters
Appears in the action area of the list header.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_list.actions', 10, function () {
return '
Acme
';
});
```
#### The top of the ticket form
uiclient.ticket_create.form.top
`website/tickets` no parameters
Appears above the new ticket form. It suits a notice that should be read before opening one.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_create.form.top', 10, function () {
return '
Acme
';
});
```
#### After the form fields
uiclient.ticket_create.fields.after
`website/tickets` no parameters
Appears after the fields on the ticket form. If you add a field of your own here, **you must handle the submitted value yourself**.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_create.fields.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the ticket form
uiclient.ticket_create.form.bottom
`website/tickets` no parameters
Appears below the ticket form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_create.form.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the ticket form sidebar
uiclient.ticket_create.sidebar.bottom
`website/tickets` no parameters
Appears at the bottom of the column beside the ticket form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_create.sidebar.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the ticket sidebar
uiclient.ticket_detail.sidebar.top
`website/tickets` no parameters
Appears at the top of the side column on the ticket detail.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_detail.sidebar.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the ticket sidebar
uiclient.ticket_detail.sidebar.bottom
`website/tickets` no parameters
Appears at the bottom of the side column.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_detail.sidebar.bottom', 10, function () {
return '
Acme
';
});
```
#### The ticket action area
uiclient.ticket_detail.actions
`website/tickets` no parameters
Appears in the action area of the ticket detail.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_detail.actions', 10, function () {
return '
Acme
';
});
```
#### The top of the conversation
uiclient.ticket_detail.thread.top
`website/tickets` no parameters
Appears above the reply thread.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_detail.thread.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the conversation
uiclient.ticket_detail.thread.bottom
`website/tickets` no parameters
Appears below the reply thread.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_detail.thread.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the reply form
uiclient.ticket_detail.reply_form.top
`website/tickets` no parameters
Appears above the customer reply box.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_detail.reply_form.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the reply form
uiclient.ticket_detail.reply_form.bottom
`website/tickets` no parameters
Appears below the reply box.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_detail.reply_form.bottom', 10, function () {
return '
Acme
';
});
```
#### After a single message
uiclient.ticket_message.body.after
`website/tickets` no parameters
Appears after **every message** in the conversation, separately. The message itself is not passed, so you cannot tell which one it is.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ticket_message.body.after', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **The message point runs on every message**
>
> The message point in the conversation is called **separately for every message** in the thread. On a long ticket that means dozens of calls, and a listener querying inside it slows the page markedly.
> **A form field you add is not saved by itself**
>
> A field you put on the ticket form is **only visible**. To handle the submitted value you must also listen on the matching hook; otherwise the customer fills it in and the value disappears.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- Order Hooks
- Support Ticket Hooks
## Customer Site Shell Hooks
https://dev.wisecp.com/en/client-site-shell-hooks
The sixteen placement points shared by every page: the head, the body, menus and the footer.
### Overview
The placement points present on every page of the site live here: the head section, the body, the menus, the footer and the system pages.
What they share is **scale**: what you place here runs on the home page, at the payment step and on an error page alike. Weigh the cost at that scale.
### Reference
#### Adding a style to the site
uiclient.head.css
`website/inc` no parameters
Appears in the head section of the site, on **every page**. Link a stylesheet of your own here.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.head.css', 10, function () {
return '
Acme
';
});
```
#### Adding a script to the site
uiclient.head.js
`website/inc` no parameters
The place to add a script on every page. It is the first thing a visitor meets: a heavy file delays the page opening.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.head.js', 10, function () {
return '
Acme
';
});
```
#### The start of the body
uiclient.body.begin
`website/inc` no parameters
Appears at the very start of the page body. It suits an announcement banner across the site.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.body.begin', 10, function () {
return '
Acme
';
});
```
#### The end of the body
uiclient.body.end
`website/inc` no parameters
Appears at the very end of the page body. The right place for modals and tracking scripts.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.body.end', 10, function () {
return '
Acme
';
});
```
#### The end of the top bar
uiclient.topbar.end
`website/inc` no parameters
Appears at the end of the top bar.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.topbar.end', 10, function () {
return '
Acme
';
});
```
#### The header action area
uiclient.header.actions
`website/inc` no parameters
Appears in the action area of the site header.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.header.actions', 10, function () {
return '
Acme
';
});
```
#### The main menu items
uiclient.nav.items
`website/inc` no parameters
Appears among the items of the main menu. Use the same item markup so the menu structure holds.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.nav.items', 10, function () {
return '
Acme
';
});
```
#### The sub-menu items
uiclient.subnav.items
`website/inc` no parameters
Appears among the items of the sub-menu.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.subnav.items', 10, function () {
return '
Acme
';
});
```
#### The user menu items
uiclient.user_menu.items
`website/inc` no parameters
Appears in the menu of a signed-in user.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.user_menu.items', 10, function () {
return '
Acme
';
});
```
#### The drawer items
uiclient.drawer.items
`website/inc` no parameters
Appears among the items of the mobile drawer. It is **separate from the main menu**: add to both if you want it in both places.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.drawer.items', 10, function () {
return '
Acme
';
});
```
#### Above the footer
uiclient.footer.before
`website/inc` no parameters
Appears immediately above the footer.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.footer.before', 10, function () {
return '
Acme
';
});
```
#### The footer columns
uiclient.footer.columns
`website/inc` no parameters
Appears among the footer columns.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.footer.columns', 10, function () {
return '
Acme
';
});
```
#### The bottom of the footer
uiclient.footer.bottom
`website/inc` no parameters
Appears at the very bottom of the footer.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.footer.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the call-to-action band
uiclient.cta_band.before
`website/inc` no parameters
Appears above the call-to-action band at the foot of the page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.cta_band.before', 10, function () {
return '
Acme
';
});
```
#### The maintenance page body
uiclient.maintenance.body
`website/inc` no parameters
Appears in the body of the maintenance page. It runs **while the site is closed**: a listener reaching the database or an outside service here can take down the page at an already bad moment.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.maintenance.body', 10, function () {
return '
Acme
';
});
```
#### The system page head
uiclient.system_page.head
`website/inc` no parameters
Appears in the head of the error and blocked pages. Those pages are shown **even when the core has failed**: give simple output with no dependencies.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.system_page.head', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **Shell points run at the payment step too**
>
> The head and body points run on **every page** of the site, the basket and the payment step included. A slow script there delays not one page but the purchase path itself.
> **Build no dependencies on the maintenance and error pages**
>
> The maintenance and system page points run at the moment the site is **already in trouble**. A listener reaching for the database or an outside service there takes down the last page the user would have seen. Give simple output with no dependencies.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Customer Panel Data Hooks](https://dev.wisecp.com/en/client-panel-data-hooks)
- [Site Content Hooks](https://dev.wisecp.com/en/client-content-hooks)
## Customer Account Screen Hooks
https://dev.wisecp.com/en/client-account-screen-hooks
The twenty-nine placement points of the dashboard, the account pages and invoices.
### Overview
The placement points on the screens a signed-in customer sees live here: the dashboard, the account pages, the balance, subscriptions, the partner programme and invoices.
Two points fall outside that pattern: the invoice detail and the licence transfer result can open for somebody **not signed in**. Your output there must not depend on a session.
### Reference
#### The top of the dashboard
uiclient.dashboard.top
`website/account` no parameters
Appears at the very top of the customer dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.dashboard.top', 10, function () {
return '
Acme
';
});
```
#### After the dashboard panels
uiclient.dashboard.panels.after
`website/account` no parameters
Appears after the panels on the dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.dashboard.panels.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the dashboard
uiclient.dashboard.bottom
`website/account` no parameters
Appears at the very bottom of the dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.dashboard.bottom', 10, function () {
return '
Acme
';
});
```
#### After the account tabs
uiclient.account.tabs.after
`website/account` no parameters
Appears after the tab bar on the account page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.account.tabs.after', 10, function () {
return '
Acme
';
});
```
#### After the account cards
uiclient.account.cards.after
`website/account` no parameters
Appears after the account summary cards.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.account.cards.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the profile form
uiclient.account.profile.form.bottom
`website/account` no parameters
Appears below the profile form. If you add a field, **you must wire up its saving too**.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.account.profile.form.bottom', 10, function () {
return '
Acme
';
});
```
#### After the security section
uiclient.account.security.after
`website/account` no parameters
Appears after the account security section.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.account.security.after', 10, function () {
return '
Acme
';
});
```
#### After the settings
uiclient.account.settings.after
`website/account` no parameters
Appears after the account settings.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.account.settings.after', 10, function () {
return '
Acme
';
});
```
#### After the sub-account list
uiclient.sub_accounts.list.after
`website/account` no parameters
Appears after the sub-user list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.sub_accounts.list.after', 10, function () {
return '
Acme
';
});
```
#### After the API keys
uiclient.api_credentials.after
`website/account` no parameters
Appears after the API key list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.api_credentials.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the balance overview
uiclient.balance_overview.bottom
`website/account` no parameters
Appears below the balance overview.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.balance_overview.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the balance history
uiclient.balance_history.top
`website/account` no parameters
Appears above the balance movement list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.balance_history.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the top-up form
uiclient.add_funds.bottom
`website/account` no parameters
Appears below the wallet top-up form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.add_funds.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the subscriptions list
uiclient.subscriptions.top
`website/account` no parameters
Appears above the list of payment agreements.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.subscriptions.top', 10, function () {
return '
Acme
';
});
```
#### The top of the partner dashboard
uiclient.affiliate_dashboard.top
`website/account` no parameters
Appears at the top of the partner programme dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.affiliate_dashboard.top', 10, function () {
return '
Acme
';
});
```
#### After the partner statistics
uiclient.affiliate_stats.after
`website/account` no parameters
Appears after the partner statistics.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.affiliate_stats.after', 10, function () {
return '
Acme
';
});
```
#### The top of the reseller dashboard
uiclient.reseller_dashboard.top
`website/account` no parameters
Appears at the top of the reseller dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.reseller_dashboard.top', 10, function () {
return '
Acme
';
});
```
#### The certificate action area
uiclient.ssl_dashboard.actions
`website/account` no parameters
Appears in the action area of the certificate dashboard.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.ssl_dashboard.actions', 10, function () {
return '
Acme
';
});
```
#### The top of the message panel
uiclient.sms_panel.top
`website/account` no parameters
Appears at the top of the bulk message panel.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.sms_panel.top', 10, function () {
return '
Acme
';
});
```
#### The top of the message form
uiclient.sms_send.top
`website/account` no parameters
Appears above the message sending form. It suits a reminder that the charge is counted per part.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.sms_send.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the message form
uiclient.sms_send.bottom
`website/account` no parameters
Appears below the message sending form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.sms_send.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the invoice page
uiclient.invoice_detail.top
`website/invoices` no parameters
Appears at the very top of the invoice detail. It runs on an invoice opened **through a share link** too, where the visitor may not be signed in.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.invoice_detail.top', 10, function () {
return '
Acme
';
});
```
#### After the invoice lines
uiclient.invoice_detail.items_after
`website/invoices` no parameters
Appears after the invoice lines.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.invoice_detail.items_after', 10, function () {
return '
Acme
';
});
```
#### After the transaction list
uiclient.invoice_detail.transactions.after
`website/invoices` no parameters
Appears after the payment movements.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.invoice_detail.transactions.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the invoice page
uiclient.invoice_detail.bottom
`website/invoices` no parameters
Appears at the very bottom of the invoice detail.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.invoice_detail.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the invoice list
uiclient.invoice_list.top
`website/invoices` no parameters
Appears above the invoice list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.invoice_list.top', 10, function () {
return '
Acme
';
});
```
#### The invoice list toolbar
uiclient.invoice_list.toolbar
`website/invoices` no parameters
Appears in the toolbar of the invoice list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.invoice_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The top of the bulk payment page
uiclient.bulk_pay.top
`website/invoices` no parameters
Appears above the screen for paying several invoices together.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.bulk_pay.top', 10, function () {
return '
Acme
';
});
```
#### Above the transfer result page
uiclient.license_transfer_result.before
`website/account` no parameters
Appears above the licence transfer result page. That page opens **through a link in an email**, so the visitor may not be signed in.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.license_transfer_result.before', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **The invoice page can open without a sign-in**
>
> The invoice detail also opens through a **share link**, where the visitor has no session. Output depending on one comes out empty there, and showing customer details opens them to somebody you cannot identify.
> **Adding a field to the profile form does not save it**
>
> A field you put on the account form is **only visible**. For the value to be kept you must also hook into the profile update flow; otherwise the customer fills it in, saves, and it disappears.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Customer Panel Data Hooks](https://dev.wisecp.com/en/client-panel-data-hooks)
- [Site Content Hooks](https://dev.wisecp.com/en/client-content-hooks)
## Customer Content Screen Hooks
https://dev.wisecp.com/en/client-content-screen-hooks
The twenty-seven placement points of the home page, content, the knowledge base and the sign-in forms.
### Overview
The placement points on the pages open to visitors live here: the home page, content and the blog, contact, the knowledge base and the sign-in forms.
Most of these pages are **open to everyone**. A script you place here is run by anyone not signed in, and anything depending on a session comes out empty.
### Reference
#### After the home hero
uiclient.home.hero.after
`website/content` no parameters
Appears after the opening block of the home page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.home.hero.after', 10, function () {
return '
Acme
';
});
```
#### The end of the home sections
uiclient.home.sections.end
`website/content` no parameters
Appears at the end of the home page sections.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.home.sections.end', 10, function () {
return '
Acme
';
});
```
#### The top of a content page
uiclient.content.top
`website/content` no parameters
Appears at the top of the content pages.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.content.top', 10, function () {
return '
Acme
';
});
```
#### After the page content
uiclient.content_page.content.after
`website/content` no parameters
Appears after the content of a plain page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.content_page.content.after', 10, function () {
return '
Acme
';
});
```
#### After a blog article
uiclient.blog_detail.content.after
`website/content` no parameters
Appears after the body of a blog article. It suits an author box or related posts.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.blog_detail.content.after', 10, function () {
return '
Acme
';
});
```
#### After the blog feed
uiclient.blog_list.feed.after
`website/content` no parameters
Appears after the blog list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.blog_list.feed.after', 10, function () {
return '
Acme
';
});
```
#### After the news feed
uiclient.news_list.feed.after
`website/content` no parameters
Appears after the news list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.news_list.feed.after', 10, function () {
return '
Acme
';
});
```
#### After the reference content
uiclient.reference_detail.content.after
`website/content` no parameters
Appears after the content of a reference page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.reference_detail.content.after', 10, function () {
return '
Acme
';
});
```
#### The top of the contact form
uiclient.contact.form.top
`website/content` no parameters
Appears above the contact form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.contact.form.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the contact form
uiclient.contact.form.bottom
`website/content` no parameters
Appears below the contact form. If you add a field, handling the submitted value is your job.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.contact.form.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the contact sidebar
uiclient.contact.aside.bottom
`website/content` no parameters
Appears at the bottom of the side column on the contact page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.contact.aside.bottom', 10, function () {
return '
Acme
';
});
```
#### After the domain search
uiclient.domain.search.after
`website/content` no parameters
Appears after the domain search box.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.domain.search.after', 10, function () {
return '
Acme
';
});
```
#### The top of the knowledge base landing
uiclient.kb_landing.content.top
`website/knowledgebase` no parameters
Appears at the top of the knowledge base landing page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_landing.content.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the knowledge base landing
uiclient.kb_landing.content.bottom
`website/knowledgebase` no parameters
Appears at the bottom of the landing page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_landing.content.bottom', 10, function () {
return '
Acme
';
});
```
#### After the search box
uiclient.kb_landing.search.after
`website/knowledgebase` no parameters
Appears after the knowledge base search box.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_landing.search.after', 10, function () {
return '
Acme
';
});
```
#### After the category header
uiclient.kb_category.header.after
`website/knowledgebase` no parameters
Appears after the header of a category page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_category.header.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the category content
uiclient.kb_category.content.bottom
`website/knowledgebase` no parameters
Appears at the bottom of the category page content.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_category.content.bottom', 10, function () {
return '
Acme
';
});
```
#### After the table of contents
uiclient.kb_article.toc.after
`website/knowledgebase` no parameters
Appears after the table of contents of an article.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_article.toc.after', 10, function () {
return '
Acme
';
});
```
#### After the article content
uiclient.kb_article.content.after
`website/knowledgebase` no parameters
Appears after the article body. It suits a feedback area or related articles.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_article.content.after', 10, function () {
return '
Acme
';
});
```
#### The article footer
uiclient.kb_article.footer
`website/knowledgebase` no parameters
Appears in the footer of an article.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_article.footer', 10, function () {
return '
Acme
';
});
```
#### The top of the knowledge base sidebar
uiclient.kb_sidebar.top
`website/knowledgebase` no parameters
Appears at the top of the knowledge base side column.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_sidebar.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the knowledge base sidebar
uiclient.kb_sidebar.bottom
`website/knowledgebase` no parameters
Appears at the bottom of the side column.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.kb_sidebar.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the sign-in form
uiclient.login.form.bottom
`website/content` no parameters
Appears below the sign-in form. That page is **open to everyone**: a script placed here runs for anyone not signed in.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.login.form.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the sign-up form
uiclient.register.form.bottom
`website/content` no parameters
Appears below the sign-up form. If you add an extra consent, **enforce it yourself**.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.register.form.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the password recovery form
uiclient.auth.forget.form.bottom
`website/content` no parameters
Appears below the password recovery form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.auth.forget.form.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the password reset form
uiclient.auth.reset.form.bottom
`website/content` no parameters
Appears below the password reset form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.auth.reset.form.bottom', 10, function () {
return '
Acme
';
});
```
#### After the invitation actions
uiclient.auth.invite.actions.after
`website/content` no parameters
Appears after the actions on the sub-user invitation page. The invited person **may hold no account yet**.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:client.auth.invite.actions.after', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **These pages are open to everyone**
>
> Code you place on the sign-in, sign-up and content pages is run by anyone, **identified or not**. Keep internal details, keys and anything meant only for a customer out of them.
> **On the invitation page the other party may have no account**
>
> The sub-user invitation page can open for somebody with **no record at all** in the system. Output depending on a session or an existing customer record comes out empty there.
### Related Articles
- [Customer Site Hooks](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- [Customer Panel Data Hooks](https://dev.wisecp.com/en/client-panel-data-hooks)
- [Site Content Hooks](https://dev.wisecp.com/en/client-content-hooks)
# Hooks / Management Panel
## Hooks in the Management Panel
https://dev.wisecp.com/en/hooks-in-the-management-panel
The 87 points that add to a screen in the management panel. Plus the 7 hooks making a new capability known to it.
### Overview
The panel takes two kinds of widening. **Screen points** add HTML to a page that already exists. **Registration hooks** make something new known to the panel: a menu entry, a dashboard box, a permission, a report.
The two serve different jobs. Putting information in a corner of a screen is a screen point. Opening a page and a permission of your own is a registration hook.
### Structure
Panel templates are plain PHP and a hook point is called inside the template itself. The naming follows the same pattern as the customer site: family, screen, spot.
```php
'Acme', 'status' => 'open', 'size' => 6];
});
// THE MENU: the return is ignored and the change goes through the global menu structure
Hook::add('register:admin.menu', 10, function () {
$GLOBALS['menus']['acme'] = ['name' => 'Acme', 'link' => 'acme/report'];
});
```
### Pitfalls
> **A menu entry opens no permission**
>
> The menu hook puts **the link** there and nothing else. The page itself still wants a permission, and a separate registration hook makes that permission known. Without both, an operator sees the entry and gets a **refused** answer on clicking it.
> **Panel templates are plain PHP**
>
> On the customer site a hook is called with a template tag. In the panel it is a direct PHP call and the returns are echoed **by hand**. So how many values a point passes changes from screen to screen. Check the parameters against the hook's entry.
> **Registration hooks share no contract**
>
> Some of the seven want you to return an array and some want you to add to a structure handed to you. Getting it the wrong way round is **silent**: you return your array, nothing appears, and no error is raised.
> **Panel hooks are not open to the customer**
>
> These points run on signed-in staff pages alone, so a customer never sees them. Even so, filter what you show **by the staff member's permissions**: not every operator should see everything.
### Related Articles
- [Management Panel Data and Gates](https://dev.wisecp.com/en/management-panel-data-and-gates)
- [Hooks on the Customer Site](https://dev.wisecp.com/en/hooks-on-the-customer-site)
- Module Lifecycle Hooks
## Management Panel Data and Gates
https://dev.wisecp.com/en/management-panel-data-and-gates
The management panel away from the screen. 23 filters change lists and forms, 6 gates sit on staff actions, and 19 hooks report an event.
### Overview
The panel's strongest hooks are here. **List and form filters** touch nearly every screen, because lists and forms come from one structure. You write one filter and it runs on dozens of screens.
That power cuts both ways. A filter that does not pick its target touches **the whole panel**. Each filter hands you the table or form name, and checking it is your job.
### Reference
#### The ones that change data
The main ones among twenty-three. Most hand the value over by reference and ignore the return. The operation filters carry a **mixed** contract acting on what you return.
- **filter:admin.table.rows**: Every list row — the cells, the row classes, the raw record. The row changes by reference; the return is ignored.
- **filter:admin.table.columns**: The list columns; you add, drop and reorder them. The array changes by reference; the return is ignored.
- **filter:admin.form_builder**: The fields the form builder produces.
- **filter:admin.dashboard.statistics**: The number cards on the dashboard.
- **filter:admin.dashboard.widgets**: The list of dashboard boxes.
- **filter:admin.menu_management**: The menu tree.
- **filter:admin.notifications**: The notifications reaching staff.
- **filter:admin.bubble_counts**: The counter bubbles on the menu.
- **filter:admin.health_status**: The system health indicator.
- **filter:admin.settings_save**: The settings about to be saved.
- **filter:admin.operation.before**: Before an operation runs — you can stop it or hand back its output.
- **filter:admin.operation.after**: After an operation ran, before the answer leaves.
- **filter:api.response**: An API answer — the body going to consumers outside the panel.
#### The ones that stop
All six sit on staff and permission work. Returning a non-empty string stops the action, and the operator reads that text as the error.
- **gate:admin.staff_create**: Opening a new staff account. Returning a non-empty string vetoes it; that text becomes the error.
- **gate:admin.staff_delete**: Deleting a staff account. Returning a non-empty string blocks the deletion; that text becomes the error.
- **gate:admin.privilege_save**: Saving a privilege group.
- **gate:admin.department_delete**: Deleting a department.
- **gate:admin.editor_upload**: Uploading a file from the editor.
- **gate:admin.password_change**: Changing a password.
#### The ones that report
- **action:admin.staff_created**: A staff account was opened.
- **action:admin.settings_saved**: Settings were saved.
- **action:admin.activity_logged**: An activity was recorded in the panel.
- **action:security.settings_updated**: Security settings changed.
- **action:admin.two_factor_changed**: Two-step verification was switched on or off.
#### A filter with a target
```php
// The second parameter IS THE TABLE NAME. Without checking it the filter runs on every list.
Hook::add('filter:admin.table.rows', 10, function (&$row, $table_name) {
if ($table_name !== 'serviceList') return null;
$id = (int) ($row['model']['id'] ?? 0);
if (Acme::flagged($id)) $row['attributes']['class'] = 'table-warning';
});
```
### Pitfalls
> **A filter that skips the table name hits every list**
>
> Row and column filters run on **every** list in the panel. Skip the name check in the second parameter and a rule meant for the service list lands on invoices, customers and tickets. Make your first line the **name check**.
> **Adding a column does not fill the cell**
>
> The column filter opens **the heading** and nothing else. The cell value for that column comes from the row filter. Writing one without the other leaves an empty column, or a cell that shows up nowhere.
> **The operation filter acts on what you return**
>
> The before-operation filter carries a **mixed** contract. An error array stops the operation. A variables array changes the inputs. An output array answers without running it at all. A wrong key name **silently** means "carry on".
> **The row filter runs once per row**
>
> On a hundred-row list the row filter runs **a hundred times**. A query inside it turns the list into a hundred queries. Gather what you need **once** into a static variable and read only that inside the listener.
### Related Articles
- [Hooks in the Management Panel](https://dev.wisecp.com/en/hooks-in-the-management-panel)
- [Customer Site Data and Gates](https://dev.wisecp.com/en/customer-site-data-and-gates)
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
## Panel Staff and Privilege Hooks
https://dev.wisecp.com/en/admin-staff-hooks
The ten hooks over staff accounts, privilege groups, departments and panel settings.
### Overview
Everything about who uses the panel lives here: staff accounts, privilege groups, support departments and an administrator’s own preferences.
These hooks share one pattern: what you receive is not the whole record but the **fields that changed**. When nothing changed the array is empty.
### Reference
#### Following a staff record being updated
actionadmin.staff_updated
`AdminStaff` only what changed
Runs after an administrator account is updated.
Parameters 3
$idintThe id of the administrator updated.
$dataarrayThe fields that **changed** on the main record: status, address, name, language, privilege or password. It **arrives empty** when none changed: this answers "what changed", not "what the record holds".
$infoarrayThe changed fields on the extra record: signature, notes, display preference and phone.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.staff_updated', 10, function ($id, $data, $info) {
// The arrays hold what CHANGED, not the whole record.
if (isset($data['privilege'])) Acme::auditPrivilegeChange($id, $data['privilege']);
});
```
#### Following a staff member being removed
actionadmin.staff_deleted
`AdminStaff` the id only
Runs after an administrator account is deleted.
Parameters 1
$idintThe id of the deleted administrator. No record is passed: if you need the name or address you must have kept it beforehand.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.staff_deleted', 10, function ($id) {
// No record is passed: keep what you need beforehand.
Acme::revokeAllTokens($id);
});
```
#### Following two-step verification being switched off
actionadmin.staff_authentication_disabled
`AdminStaff` security weakens
Runs after two-step verification is switched off for an administrator. It is a **weakening of security** and is usually done by somebody else.
Parameters 2
$idintThe administrator it was switched off for.
$methodstringThe key of the method switched off.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.staff_authentication_disabled', 10, function ($id, $method) {
// Security just weakened: do not stay quiet.
Acme::alertSecurityTeam($id, $method);
});
```
#### Following a privilege group being saved
actionadmin.privilege_saved
`AdminStaff` id unreliable on create
Runs when a privilege group is created or edited.
Parameters 4
$idintThe id of the group. ? **On the create path it is not the new id** and may be zero. Tell a new record from the operation type, not from this.
$typestringThe operation: `add` or `edit`.
$namestringThe name of the group.
$permsstringThe permission keys as saved, comma separated. It is not an array: split it to work with it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.privilege_saved', 10, function ($id, $type, $name, $perms) {
// Tell a new record from the operation TYPE, not the id.
if ($type === 'add') Acme::noteNewRole($name, explode(',', $perms));
});
```
#### Following an administrator updating their own profile
actionadmin.profile_updated
`AdminStaff` their own profile
Runs when an administrator updates their own profile.
Parameters 3
$admin_idintThe administrator whose profile changed.
$data_updatesarrayThe changed fields on the main record: name and address. Empty when nothing changed.
$info_updatesarrayWhat changed on the extra record: the phone fields.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.profile_updated', 10,
function ($admin_id, $data_updates, $info_updates) {
if (isset($data_updates['email'])) Acme::alertEmailChange($admin_id);
});
```
#### Following panel preferences changing
actionadmin.preferences_updated
`AdminStaff` display preferences
Runs when an administrator changes how the panel looks for them.
Parameters 3
$admin_idintThe administrator whose preferences changed.
$info_setsarrayThe display preferences that changed: light or dark, and the menu state.
$data_setsarrayWhat changed on the main record: their language.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.preferences_updated', 10,
function ($admin_id, $info_sets, $data_sets) {
if (isset($data_sets['lang'])) Acme::syncLocale($admin_id, $data_sets['lang']);
});
```
#### Following a department being saved
actionadmin.department_saved
`AdminStaff` id correct on create
Runs when a support department is created or edited.
Parameters 3
$idintThe department id. Unlike the privilege hook, the id here is **correct on the create path too**.
$typestringThe operation: `add` or `edit`.
$set_dataarrayThe saved fields: rank, appointees and icon.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.department_saved', 10, function ($id, $type, $set_data) {
// Here the id is correct on the create path as well.
Acme::syncDepartment($id, $set_data);
});
```
#### Following a department being deleted
actionadmin.department_deleted
`AdminStaff` after deletion
Runs after a support department is deleted.
Parameters 2
$idintThe id of the deleted department.
$detailarrayThe record of the deleted department, name included.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.department_deleted', 10, function ($id, $detail) {
Acme::dropDepartmentRoute($id);
});
```
#### Following logs being cleared
actionadmin.logs_cleared
`AdminTools` cannot be undone
Runs when an administrator clears a log type. What is deleted **does not come back**.
Parameters 2
$typestringWhat was cleared: user actions, errors or module records.
$datestringThe cut-off; records up to and **including** that date are gone.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.logs_cleared', 10, function ($type, $date) {
// What is gone stays gone: note it in your own archive.
Acme::noteRetention($type, $date);
});
```
#### Following notification settings being saved
actionadmin.notification_settings_saved
`AdminSettings` template engine
Runs when the engine used for notification templates changes. That setting decides how **every** notification is produced.
Parameters 2
$enginestringThe chosen engine: none, Smarty or Twig.
$admin_idintThe administrator who changed it; zero when there is no session.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.notification_settings_saved', 10, function ($engine, $admin_id) {
// Every notification is produced through this setting.
Acme::notifyOps('notification engine: ' . $engine);
});
```
### Pitfalls
> **The id is unreliable when a privilege group is created**
>
> On the create path the id in the privilege hook is **not the id of the new record** and may be zero. Tell a new record from the operation type. The department hook does not share this flaw; there the id is right on both paths.
> **The arrays carry what changed, not the whole record**
>
> The arrays in the staff, profile and preference hooks hold only the **fields that changed**. A field being absent does not mean "removed", it means "untouched". Read the record separately if you need its current state.
### Related Articles
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Panel Analytics Hooks
https://dev.wisecp.com/en/admin-analytics-hooks
The six hooks over report figures, date ranges, charts and live counters.
### Overview
Every number on the report pages passes through these hooks: summary figures, time series, distributions and finance totals. Beside them sits the read-only event of the live counters.
One rule runs through all of them: **keep the shape**. The chart library and the queries that follow expect particular keys; a missing or mismatched structure quietly yields an empty report.
### Reference
#### Following a live metric poll
actionadmin.analytics.realtime_polled
`admin/analytics` read only
Runs when the live counters on the board refresh. It repeats **at regular intervals** while the page is open.
Parameters 1
$statsarrayThe live metrics: how many are online, visitors in the last five minutes, and map markers. A copy is passed: **changing it has no effect**. It is deliberately an event, not a filter.
Return 1
voidThe return is ignored; the data cannot be changed.
Listener PHP
```php
Hook::add('action:admin.analytics.realtime_polled', 10, function ($stats) {
// A copy is passed: changing it has no effect.
Acme::pushMetric('online', (int) ($stats['online_count'] ?? 0));
});
```
#### Changing the report date range
filteradmin.analytics.date_range
`admin/analytics` keys must survive
Runs after the date range picked by the user is resolved. Every report query uses that range.
Parameters 2
$resultarrayby linkThe resolved range: start, end, the previous period’s start and end, and the day count. ? **Every key must survive**: a missing one breaks the queries that follow and the report comes out empty.
$rangestringThe raw range text from the user.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.analytics.date_range', 10, function (&$result, $range) {
// Every key must stay: a missing one empties the report.
$result['start'] = Acme::fiscalStart($result['start']);
});
```
#### Changing the summary figures
filteradmin.analytics.kpis
`admin/analytics` shape follows the section
Runs once the summary figures at the top of a report page are worked out.
Parameters 3
$kpisarrayby linkThe values worked out. ? **Its shape follows the section**: the keys in the client report are not the keys in the service report. Check the section before reaching for a key.
$sectionstringThe report section: clients, services or support.
$rangearrayThe active date range.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.analytics.kpis', 10, function (&$kpis, $section, $range) {
// The shape follows the section: check it first.
if ($section !== 'clients') return;
$kpis['acme_churn'] = Acme::churnRate($range);
});
```
#### Changing the time series
filteradmin.analytics.trend_series
`admin/analytics` equal lengths required
Runs once the chart data is worked out.
Parameters 3
$trendarrayby linkLabels and one or more value series. ? **The labels and the series must be the same length**; the chart draws its axes from that. Keep the existing series keys and add a new series under its own key.
$reportstringThe report key: income, expense, profit and loss, clients, services or support.
$rangearrayThe active date range.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.analytics.trend_series', 10, function (&$trend, $report, $range) {
// Labels and series must be the same length.
if ($report !== 'income') return;
$trend['acme_forecast'] = Acme::forecast(count($trend['labels'] ?? []));
});
```
#### Changing the distribution data
filteradmin.analytics.distribution
`admin/analytics` fixed item shape
Runs once the distribution chart data is worked out.
Parameters 4
$dataarrayby linkThe distribution items. Each item must carry a **label and a value**; the chart library expects that shape and any other quietly yields an empty chart.
$entitystringWhat is distributed: clients, services or tickets.
$typestringThe kind: status, country, language, product, period, priority, department, staff or response time.
$rangearrayThe active date range.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.analytics.distribution', 10,
function (&$data, $entity, $type, $range) {
// Every item must carry a label and a value.
if ($entity === 'client' && $type === 'country')
$data = Acme::mergeSmallCountries($data);
});
```
#### Changing the finance summary
filteradmin.analytics.invoice_report_totals
`admin/analytics` currency filtered
Runs once the summary totals of a finance report are worked out.
Parameters 4
$totalsarrayby linkThe summary totals: count, amount, day count, daily average and currency.
$reportstringWhich report: income, expense, profit and loss, tax, cancelled, refunded or payment method.
$rangearrayThe active date range.
$currency_idintThe currency filtered on; a **zero** means the base currency.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.analytics.invoice_report_totals', 10,
function (&$totals, $report, $range, $currency_id) {
// A zero currency means the base currency.
if ($report === 'income') $totals['acme_target'] = Acme::monthlyTarget($currency_id);
});
```
### Pitfalls
> **Dropping a date-range key empties the report**
>
> Every key in the range array is read by the queries that follow. Removing one or renaming it breaks the figure and chart queries; what appears on screen is not an error but an **empty report**, which makes it hard to spot.
> **Labels and series must be the same length**
>
> If the label count and the value count part ways in a time series the chart axes slip. Build a new series to the length of the existing labels, and keep the series keys already there.
### Related Articles
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Panel Screen Data Hooks
https://dev.wisecp.com/en/admin-screen-data-hooks
The thirteen hooks over what the customer, service and tool screens show.
### Overview
The hooks that change what panel screens show live here: the customer detail and list, the service management cards, add-on buttons, critical notifications and the theme version lookup.
Two differ from the rest: the profile tabs and the security accordion hand you a **component object** rather than an array, and you add through a method call.
### Reference
#### Changing the customer extra details
filteradmin.client_detail.info
`admin/users` passed by link
Runs once the extra detail fields on a customer page are read.
Parameters 2
$client_infoarrayby linkThe extra detail pairs. You may overwrite an existing key or add a new one.
$user_idintThe customer id.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.client_detail.info', 10, function (&$client_info, $user_id) {
$client_info['acme_tier'] = Acme::tierOf($user_id);
});
```
#### Adding a sub-tab to a customer profile
filteradmin.client_detail.profile_subtabs
`admin/users` a component object
Runs while the vertical tabs of a customer profile are built. Add a tab of your own here.
Parameters 3
$profileTabobjectby linkThe tab component. It is an **object**, not an array: you add a tab by calling its add method, not by appending to a list.
$userarrayThe active customer record.
$user_idintThe customer id.
Return 1
voidThe return is ignored; the change happens through the object’s method.
Listener PHP
```php
Hook::add('filter:admin.client_detail.profile_subtabs', 10,
function (&$profileTab, $user, $user_id) {
// An object, not an array: call its method.
$profileTab->add('acme', 'Acme', Acme::renderPanel($user_id));
});
```
#### Adding a section to the security area
filteradmin.client_detail.security_accordion
`admin/users` a component object
Runs while the security settings accordion of a customer is built.
Parameters 3
$secAccordionobjectby linkThe accordion component; add a section through its add method.
$client_infoarrayThe extra details of the customer.
$user_idintThe customer id.
Return 1
voidThe return is ignored; the change happens through the object.
Listener PHP
```php
Hook::add('filter:admin.client_detail.security_accordion', 10,
function (&$secAccordion, $client_info, $user_id) {
$secAccordion->add('acme-sessions', 'Acme sessions', Acme::sessions($user_id));
});
```
#### Changing the customer statistics
filteradmin.client_detail.statistics
`admin/users` passed by link
Runs once the counters on a customer page are worked out.
Parameters 2
$user_statsarrayby linkThe statistics: active and inactive services, invoices and tickets.
$user_idintThe customer id.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.client_detail.statistics', 10, function (&$user_stats, $user_id) {
$user_stats['acme_open_cases'] = Acme::openCases($user_id);
});
```
#### Changing the customer list filters
filteradmin.client_list.filters
`admin/users` the model must support it
Runs once the filter criteria of the customer list are built.
Parameters 1
$dynamic_filterarrayby linkThe filter criteria: group, status, language, country, address and date. ? A key you add **must also be handled in the listing query**; otherwise the filter appears but narrows nothing.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.client_list.filters', 10, function (&$dynamic_filter) {
// A new key must be handled in the listing query too.
$dynamic_filter['acme_tier'] = Acme::tierFilterValue();
});
```
#### Changing the service management cards
filteradmin.service_detail.management_cards
`admin/services` two lists together
Runs once the management cards on a service detail are prepared. Add a card of your own, hide one, or change the order.
Parameters 1
$contextarrayby linkTwo lists together: `cards` holds the card content and `layout` says which card sits in which column and in what order. ? **Update both**: a card missing from the layout never appears, and a layout key with no card is quietly skipped.
Return 1
voidThe return is ignored; you write over the context.
Listener PHP
```php
Hook::add('filter:admin.service_detail.management_cards', 10, function (&$context) {
// Update BOTH: the card and the layout.
$context['cards']['acme'] = Acme::renderCard($context['service'] ?? []);
$context['layout']['right'][] = 'acme';
});
```
#### Changing the add-on settings buttons
filteradmin.addon_configure.buttons
`admin/tools` emptying removes them all
Runs once the buttons on an add-on settings page are prepared.
Parameters 1
$buttonsarrayby linkThe button map; each carries its text, class, icon and click action. Empty the array entirely and **no button appears**.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.addon_configure.buttons', 10, function (&$buttons) {
// Emptying it entirely leaves no buttons at all.
$buttons['acme-sync'] = [
'text' => 'Sync Acme',
'class' => 'btn btn-outline-primary',
'icon' => 'bi bi-arrow-repeat',
'onclick' => 'acmeSync()',
];
});
```
#### Changing the address of an uploaded image
filteradmin.editor_upload_url
`admin/tools` passed by link
Runs after the address of an image uploaded into the editor is produced. This is how you move images onto a delivery network.
Parameters 2
$urlstringby linkThe address produced. Leave it alone and the local one stays.
$file_pathstringThe full path of the file on the server.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.editor_upload_url', 10, function (&$url, $file_path) {
$url = Acme::pushToCdn($file_path) ?: $url;
});
```
#### Following an image upload
actionadmin.editor_image_uploaded
`admin/tools` address after the filter
Runs after an image is uploaded into the editor.
Parameters 2
$file_pathstringThe full path of the file on the server.
$urlstringThe final address, **as it stands after the address filter** ran.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.editor_image_uploaded', 10, function ($file_path, $url) {
// The address is the one AFTER the filter ran.
Acme::noteAsset($file_path, $url);
});
```
#### Adding to the critical notification list
filteradmin.notifications.critical
`admin/inc` fixed item shape
Runs once the critical notification list in the panel header is prepared.
Parameters 1
$critical_transaction_notificationsarrayby linkThe notification items. Each must carry the fields the template expects: id, icon, type, message, date, read state and buttons. An item missing one breaks the display.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:admin.notifications.critical', 10, function (&$critical_transaction_notifications) {
// Fill every field the template expects.
foreach (Acme::criticalAlerts() as $a) $critical_transaction_notifications[] = $a;
});
```
#### Following a panel notification
actionadmin.notified
`Notification` zero means not written
Runs when a system notification lands in the panel.
Parameters 4
$namestringThe event name.
$dataarrayThe event data: message placeholders and what is used to spot repeats.
$levelstringThe level: error, warning, information or success.
$event_idintThe id of the record created. **A zero means nothing was written**: either the same notice already existed or the write failed. Test before using the id.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:admin.notified', 10, function ($name, $data, $level, $event_id) {
// Zero means nothing was written.
if ($level === 'error' && $event_id) Acme::page($name, $data);
});
```
#### Taking over the theme version lookup
filteradmin.theme_version_check
`admin/settings` first filled wins
Runs before a theme is asked about a new version. Return an answer and **no remote call is made**.
Parameters 2
$keystringThe theme folder key.
$manifestarrayThe theme manifest: its update address and installed version.
Return 1
string|null**A filled text is taken as the raw response** and the call is skipped. The **first** filled return by priority wins and the rest never run. With an empty return the core makes its usual request.
Listener PHP
```php
Hook::add('filter:admin.theme_version_check', 10, function ($key, $manifest) {
// A filled return means NO remote call is made.
if (!str_starts_with($key, 'Acme')) return null;
return Acme::versionJson($key);
});
```
#### Adjusting the theme version response
filteradmin.theme_version_response
`admin/settings` the raw response
Runs after the version response arrives and before it is decoded. Its sibling picks the source; this hook **adjusts what came back**.
Parameters 2
$keystringby linkThe theme key. It is passed by link but already **consumed**: changing it has no effect.
$manifestarrayby linkThe theme manifest, also consumed.
Return 1
voidThe return is ignored; you write over the raw response. The core then decodes it; with no version field the result counts as empty.
Listener PHP
```php
Hook::add('filter:admin.theme_version_response', 10, function (&$key, &$manifest) {
// Both parameters are consumed: changing them has no effect.
Acme::noteVersionCheck($key);
});
```
### Pitfalls
> **Adding a card takes two lists**
>
> In the service management cards the content sits in one list and the **layout in another**. Add only the content and the card never appears; write only a name into the layout and that name is quietly skipped. Update both.
> **The tabs and the accordion are objects, not arrays**
>
> The profile sub-tabs and the security accordion hand you a **component object**. A listener treating it like an array fails; you add through the object’s own method.
### Related Articles
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Panel Customer Screen Hooks
https://dev.wisecp.com/en/admin-client-screen-hooks
The nineteen placement points of the customer screens: summary cards, tabs, the list toolbar and the creation form.
### Overview
The placement points of the customer screens live here. They all work the same way. The HTML you return appears at that point. Return `null` when you have nothing to add.
Two points fall outside that pattern. **Adding a tab** receives an object rather than HTML, and the addition happens through a method call. The **document field form** is collected once as the page opens and then fixed. It cannot vary with the field being edited.
### Reference
#### The top of the summary tab
uiadmin.client_detail.summary.top
`admin/users/detail` above the cards
Appears at the very top of the customer summary, above the statistic cards. The right place for a risk banner, a last-contact note or a key-account warning.
Parameters 3
$userarrayThe full customer record.
$user_idintThe customer id.
$user_statsarrayThe counters worked out: active and inactive services, invoices, tickets.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.summary.top', 10,
function ($user, $user_id, $user_stats) {
$score = Acme::riskScore($user_id);
if ($score < 70) return null; // eklenecek bir sey yoksa null
return '
Risk skoru: ' . (int) $score . '
';
});
```
#### Adding a row to the information card
uiadmin.client_detail.summary.info_card
`admin/users/detail` a row inside the card
Appears after the last row of the information card. The place for a field such as an outside customer number, the referral source or an account manager.
Parameters 3
$userarrayThe full customer record.
$client_infoarrayThe extra detail pairs of the customer.
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.summary.info_card', 10,
function ($user, $client_info, $user_id) {
$crm = Acme::crmId($user_id);
if ($crm === '') return null;
// Cikti kacissiz basilir: dis degeri kendiniz temizleyin.
return '
CRM
'
. htmlspecialchars($crm) . '
';
});
```
#### Adding an operation to the actions card
uiadmin.client_detail.summary.action_cards
`admin/users/detail` an operation box
Appears after the last operation in the actions card. It puts an operation of your own beside the built-in ones.
Parameters 2
$userarrayThe full customer record.
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.summary.action_cards', 10, function () {
return '
Acme
';
});
```
#### The bottom of the summary tab
uiadmin.client_detail.summary.bottom
`admin/users/detail` below the cards
Appears once the cards of the summary tab end. The place for a card or an information panel of your own.
Parameters 2
$userarrayThe full customer record.
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.summary.bottom', 10, function () {
return '
Acme
';
});
```
#### A badge or button in the title area
uiadmin.client_detail.header_actions
`admin/users/detail` beside the badges
Appears at the end of the status badges in the page title. Put a badge of your own or a shortcut button here.
Parameters 3
$userarrayThe full customer record.
$user_idintThe customer id.
$client_infoarrayThe resolved customer details: kind, tax status and protection flags.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.header_actions', 10, function () {
return '
Acme
';
});
```
#### A new tab on the customer detail
uiadmin.client_detail.tabs
`admin/users/detail` an object, not an array
Runs once every core tab is built. Unlike the other placement points you **do not return HTML** here: you add the tab through the object’s method.
Parameters 3
$tabobjectThe tab object; add a new tab through its method.
$userarrayThe full customer record.
$user_idintThe customer id.
Return 1
voidThe return is **not used**. This point shows no HTML: the change happens by calling the object’s method. A listener returning HTML quietly does nothing here.
Listener PHP
```php
Hook::add('ui:admin.client_detail.tabs', 10, function ($tab, $user, $user_id) {
// HTML DONDURMEYIN: sekme nesneye eklenir.
$tab->add('acme', 'Acme', Acme::renderTab($user_id));
});
```
#### The bottom of the profile tab
uiadmin.client_detail.profile.bottom
`admin/users/detail` below the profile
Appears once the vertical tabs of the profile are on screen. It suits a verification summary or an extra preference section.
Parameters 3
$userarrayThe full customer record.
$client_infoarrayThe extra details of the customer.
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.profile.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the contacts tab
uiadmin.client_detail.contacts.top
`admin/users/detail` top of the tab
Appears above the address and contact list. It suits an address verification state or a warning about a missing billing address.
Parameters 3
$userarrayThe full customer record.
$user_idintThe customer id.
$user_addressesarrayThe address and contact records of the customer.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.contacts.top', 10, function () {
return '
Acme
';
});
```
#### The top of the sub-users tab
uiadmin.client_detail.subusers.top
`admin/users/detail` top of the tab
Appears above the sub-user list. It suits a warning about unaccepted invitations or a note on permission policy.
Parameters 2
$userarrayThe full customer record.
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.subusers.top', 10, function () {
return '
Acme
';
});
```
#### The top of the invoices tab
uiadmin.client_detail.invoices.top
`admin/users/detail` top of the tab
Appears above the invoice table. It suits an outstanding balance warning or the state of automatic payment.
Parameters 1
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.invoices.top', 10, function () {
return '
Acme
';
});
```
#### The top of the services tab
uiadmin.client_detail.orders.top
`admin/users/detail` top of the tab
Appears above the service and order list. It suits a renewal warning or a provisioning failure banner.
Parameters 1
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.orders.top', 10, function () {
return '
Acme
';
});
```
#### The top of the support tab
uiadmin.client_detail.tickets.top
`admin/users/detail` top of the tab
Appears above the ticket table. It suits a count of open tickets or a satisfaction summary.
Parameters 1
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.tickets.top', 10, function () {
return '
Acme
';
});
```
#### The top of the notes tab
uiadmin.client_detail.notes.top
`admin/users/detail` top of the tab
Appears above the note list. The place to show system notes coming from an outside source.
Parameters 2
$user_idintThe customer id.
$notesarrayThe notes of the customer.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.notes.top', 10, function () {
return '
Acme
';
});
```
#### The very bottom of the customer page
uiadmin.client_detail.bottom
`admin/users/detail` end of the page
Appears at the very end of the page, immediately before the footer. It suits a panel that belongs to no tab.
Parameters 2
$userarrayThe full customer record.
$user_idintThe customer id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_detail.bottom', 10, function () {
return '
Acme
';
});
```
#### The customer list toolbar
uiadmin.client_list.toolbar
`admin/users` no parameters
Appears in the button group above the list. Add a button for an export or a bulk action of your own.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_list.toolbar', 10, function () {
return '
'
. ' ';
});
```
#### Above the table on the customer list
uiadmin.client_list.before_table
`admin/users` above the table
Appears after the statistic card and the filter panel, immediately above the table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_list.before_table', 10, function () {
return '
Acme
';
});
```
#### Above the customer creation form
uiadmin.client_create.before_content
`admin/users` above the form
Appears above the new customer form. It suits an information banner or an extra instruction.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_create.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the customer creation form
uiadmin.client_create.bottom
`admin/users` below the form
Appears once the new customer form ends, at the bottom of the page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.client_create.bottom', 10, function () {
return '
Acme
';
});
```
#### An extra section on the document field form
uiadmin.document_field.form
`admin/users` collected once
Puts an extra section into the add and edit window of the document verification fields. If you introduced a field type of your own, ask for its settings here.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe HTML you return appears. ? Because the window is built in the browser, the output is collected **once as the page opens** and embedded as a constant: it **cannot vary** with the field being edited. If you need per-field behaviour, show all of it and choose in your own code.
Listener PHP
```php
Hook::add('ui:admin.document_field.form', 10, function () {
// The output is collected once: it cannot vary per field.
return '
Acme check '
. '
';
});
```
### Pitfalls
> **The output enters the page unescaped**
>
> Whatever you return at these points enters the page as it stands. Embedding a value from outside (a customer name, a response from another system, form input) directly creates a **code execution hole in the panel**. Escape the value yourself.
> **The tab point takes no HTML**
>
> The tab point looks like the others but **shows no HTML**: it hands you an object and the tab is added through its method. A listener returning HTML quietly does nothing here, and raises no error either, which makes it hard to spot.
### Related Articles
- [Panel Screen Data Hooks](https://dev.wisecp.com/en/admin-screen-data-hooks)
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
## Panel Service Screen Hooks
https://dev.wisecp.com/en/admin-service-screen-hooks
The eighteen placement points of the service screens: the detail tabs, the title area and the toolbars of the side lists.
### Overview
The placement points of the service screens live here. They cover every tab of the detail page, the title area and the toolbars of the side lists.
Most detail points hand you the service record. Some add something that **can arrive empty**: the product record when the product was gone, or the module instance when the service has no server. Test before reaching into those.
### Reference
#### A badge or button in the service title
uiadmin.service_detail.header_actions
`admin/services/detail` the title area
Appears in the title row of the service detail. Put the state on the remote panel or a shortcut of your own here.
Parameters 1
$servicearrayThe active service record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.header_actions', 10, function () {
return '
Acme
';
});
```
#### A new tab on the service detail
uiadmin.service_detail.tabs
`admin/services/detail` an object, not an array
Runs once the core tabs are built. You do not return HTML: you add the tab through the object’s method. Two flags tell you which tab makes sense.
Parameters 4
$tabobjectThe tab object.
$servicearrayThe full service record.
$is_domainboolWhether the service is a domain. Server tabs make no sense on a domain; decide from this.
$has_moduleboolWhether the service sits on a server. A false here leaves a tab pulling remote data empty.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.service_detail.tabs', 10,
function ($tab, $service, $is_domain, $has_module) {
// Sunucusu olmayan hizmette uzak panel sekmesi bos cikar.
if (!$has_module) return;
$tab->add('acme', 'Acme', Acme::renderTab((int) ($service['id'] ?? 0)));
});
```
#### The bottom of the details tab
uiadmin.service_detail.details.bottom
`admin/services/detail` the product may be empty
Appears below the service details.
Parameters 2
$servicearrayThe active service record.
$productarrayThe product behind the service. It **arrives empty** when the product was deleted or the service is not tied to one.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.details.bottom', 10, function ($service, $product) {
// Urun BOS gelebilir.
if (!$product) return null;
return '
' . htmlspecialchars(Acme::planNote($product)) . '
';
});
```
#### The bottom of the management tab
uiadmin.service_detail.management.bottom
`admin/services/detail` the module may be empty
Appears below the server management tools.
Parameters 2
$servicearrayThe active service record.
$moduleobjectThe loaded server module. ? It **can arrive empty** when the service has no server or the module failed to load. Test before calling a method.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.management.bottom', 10, function ($service, $module) {
// Modul BOS gelebilir: metot cagirmadan once sinayin.
if (!$module) return null;
return Acme::renderRemotePanel($module, $service);
});
```
#### The top of the add-ons tab
uiadmin.service_detail.addons.top
`admin/services/detail` top of the tab
Appears above the list of service add-ons.
Parameters 1
$servicearrayThe active service record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.addons.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the requirements tab
uiadmin.service_detail.requirements.bottom
`admin/services/detail` the filled answers
Appears below the details asked of the customer during the order.
Parameters 2
$servicearrayThe active service record.
$requirementsarrayThe requirements filled in for this service.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.requirements.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the history tab
uiadmin.service_detail.history.bottom
`admin/services/detail` below the history
Appears below the service history. The place to put your own record beside the core one.
Parameters 1
$servicearrayThe active service record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.history.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the package change tab
uiadmin.service_detail.upgrade.top
`admin/services/detail` the remainder in hand
Appears above the package upgrade screen. The remaining days and amount are in your hands, so you can show your own pricing note here.
Parameters 3
$servicearrayThe active service record.
$productarrayThe current product record.
$remainingarrayThe remainder: days used, days left and the amount left.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.upgrade.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the transfer tab
uiadmin.service_detail.transfer.bottom
`admin/services/detail` carries a secret
Appears below the domain transfer screen.
Parameters 2
$servicearrayThe active domain record.
$service_optionsarrayThe service options: the transfer lock and the **authorisation code**. ? That code is a secret: keep it off the screen and out of your records.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.transfer.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the verification tab
uiadmin.service_detail.verification.bottom
`admin/services/detail` domain verification
Appears below the domain contact verification screen.
Parameters 2
$servicearrayThe active domain record.
$service_idintThe service id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.verification.bottom', 10, function () {
return '
Acme
';
});
```
#### The very bottom of the service page
uiadmin.service_detail.bottom
`admin/services/detail` end of the page
Appears at the very end of the page. It suits a panel that belongs to no tab.
Parameters 1
$servicearrayThe service record on screen.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_detail.bottom', 10, function () {
return '
Acme
';
});
```
#### The service list toolbar
uiadmin.service_list.toolbar
`admin/services` no parameters
Appears in the button group above the service list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the service list
uiadmin.service_list.before_table
`admin/services` no parameters
Appears immediately above the service table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The add-on list toolbar
uiadmin.service_addon_list.toolbar
`admin/services` no parameters
Appears in the toolbar of the service add-on list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_addon_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the add-on list
uiadmin.service_addon_list.before_table
`admin/services` no parameters
Appears immediately above the add-on table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_addon_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The cancellation request toolbar
uiadmin.service_cancellation_list.toolbar
`admin/services` no parameters
Appears in the toolbar of the cancellation request list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_cancellation_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The transfer list toolbar
uiadmin.service_transfer_list.toolbar
`admin/services` no parameters
Appears in the toolbar of the service transfer list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_transfer_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The package change list toolbar
uiadmin.service_updowngrade_list.toolbar
`admin/services` no parameters
Appears in the toolbar of the package upgrade and downgrade list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.service_updowngrade_list.toolbar', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **The module instance can be empty**
>
> The module parameter on the management tab is **empty** when the service has no server or the module failed to load. A listener calling a method straight away raises a fatal error there and takes **the whole page** down: it is not your panel that breaks but the administrator’s service screen.
> **The transfer point carries the authorisation code**
>
> The options array on the transfer tab holds the **authorisation code** of the domain. Whoever sees that code can move the domain to another registrar: keep it off the screen, out of your logs and away from outside services.
### Related Articles
- [Panel Screen Data Hooks](https://dev.wisecp.com/en/admin-screen-data-hooks)
- [Service Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
## Panel Support Screen Hooks
https://dev.wisecp.com/en/admin-support-screen-hooks
The twenty-one placement points of the support screens: the ticket detail, the reply form, the list rows and the department forms.
### Overview
The placement points of the support screens live here: every part of the ticket detail, the list rows and the department forms.
A few points on the ticket detail hand you a **privilege flag**. It is not a gate: the core disables its own buttons with it, but it does not stop your output. If you show something that needs the privilege, do the check yourself.
### Reference
#### A badge or button in the ticket title
uiadmin.tickets_detail.header_actions
`admin/tickets/detail` the title area
Appears in the title row of the ticket detail. It suits a case number in another system or a shortcut of your own.
Parameters 1
$ticketarrayThe active ticket record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tickets_detail.header_actions', 10, function () {
return '
Acme
';
});
```
#### The top of the side column
uiadmin.ticket_detail.sidebar_top
`admin/tickets/detail` top of the side column
Appears in the side column of the ticket detail, above the first card.
Parameters 2
$ticketarrayThe active ticket record.
$opPrivboolWhether the viewer holds the operation privilege. ? This is **information**, not a gate: when false the core disables its own buttons but does not stop your output. If you show something that needs the privilege, **check it yourself**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.sidebar_top', 10, function () {
return '
Acme
';
});
```
#### Adding an operation to the side column
uiadmin.ticket_detail.sidebar_actions
`admin/tickets/detail` an operation box
Appears among the operation boxes in the side column. It puts a ticket operation of your own beside the built-in ones.
Parameters 2
$ticketarrayThe active ticket record.
$opPrivboolWhether the viewer holds the operation privilege. ? This is **information**, not a gate: when false the core disables its own buttons but does not stop your output. If you show something that needs the privilege, **check it yourself**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.sidebar_actions', 10, function ($ticket, $opPriv) {
// Yetki bilgisi kapi DEGIL: kendiniz sinayin.
if (!$opPriv) return null;
return '
Acme
';
});
```
#### A row on the ticket details card
uiadmin.ticket_detail.details_card.meta
`admin/tickets/detail` the details card
Appears among the fields of the ticket details card. Add metadata of your own beside the core fields.
Parameters 1
$ticketarrayThe active ticket, with its mail source, department and reference in it.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.details_card.meta', 10, function () {
return '
Acme
';
});
```
#### Above the conversation
uiadmin.ticket_detail.conversation.before
`admin/tickets/detail` above the conversation
Appears immediately above the reply thread. It suits context or a warning from another system.
Parameters 1
$ticketarrayThe active ticket record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.conversation.before', 10, function () {
return '
Acme
';
});
```
#### The top of the reply form
uiadmin.ticket_detail.reply_form.top
`admin/tickets/detail` top of the reply form
Appears above the box staff write their reply in. It suits a warning that should be seen before writing.
Parameters 2
$ticketarrayThe active ticket record.
$opPrivboolWhether the viewer holds the operation privilege. ? This is **information**, not a gate: when false the core disables its own buttons but does not stop your output. If you show something that needs the privilege, **check it yourself**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.reply_form.top', 10, function () {
return '
Acme
';
});
```
#### The reply form toolbar
uiadmin.ticket_detail.reply_form.toolbar
`admin/tickets/detail` the form toolbar
Appears in the toolbar of the reply form. Put your own insert or template button here.
Parameters 1
$ticketarrayThe active ticket record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.reply_form.toolbar', 10, function () {
return '
Acme
';
});
```
#### Below the reply editor
uiadmin.ticket_detail.reply_editor.after
`admin/tickets/detail` below the editor
Appears immediately below the text editor. It suits an extra option or a confirmation box before sending.
Parameters 1
$ticketarrayThe active ticket record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.reply_editor.after', 10, function () {
return '
Acme
';
});
```
#### Below the canned replies
uiadmin.ticket_detail.canned_replies.after
`admin/tickets/detail` the language is separate
Appears below the canned reply options. The place to add a template source of your own.
Parameters 2
$ticketarrayThe active ticket record.
$client_langstringThe active interface language. Canned replies load in the customer’s language, and since the template does not hold that value the interface language is passed instead. The two **may differ**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.canned_replies.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the internal note form
uiadmin.ticket_detail.note_form.bottom
`admin/tickets/detail` the internal note form
Appears below the internal note box. Notes are never shown to the customer.
Parameters 1
$ticketarrayThe active ticket record.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.note_form.bottom', 10, function () {
return '
Acme
';
});
```
#### A new tab on the ticket detail
uiadmin.ticket_detail.tabs
`admin/tickets/detail` an object, not an array
Runs once the tabs of the ticket detail are built. You do not return HTML: you add the tab through the object’s method.
Parameters 2
$tabobjectThe tab object. Being an object, it changes for good without a by-link mark.
$ticketarrayThe full ticket record.
Return 1
voidThe return is **not used**. This point shows no HTML.
Listener PHP
```php
Hook::add('ui:admin.ticket_detail.tabs', 10, function ($tab, $ticket) {
$tab->add('acme', 'Acme', Acme::renderTab((int) ($ticket['id'] ?? 0)));
});
```
#### The very bottom of the ticket page
uiadmin.tickets_detail.bottom
`admin/tickets/detail` end of the page
Appears at the very end of the page.
Parameters 1
$ticketarrayThe ticket record on screen.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tickets_detail.bottom', 10, function () {
return '
Acme
';
});
```
#### A badge on a list row
uiadmin.tickets_list.row_badges
`admin/tickets` per row
Appears on **every row** of the ticket list. It puts a status badge of your own beside the core ones.
Parameters 1
$modelarrayThe row data: id, status, read mark, department and title. ? The hook runs per row, so a listener querying the database here produces **hundreds of queries per page**. Collect what you need beforehand.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tickets_list.row_badges', 10, function ($model) {
// SATIR BASINA calisir: burada sorgu yapmayin, onceden toplayin.
if (!Acme::isEscalated((int) ($model['id'] ?? 0))) return null;
return '
Acme ';
});
```
#### The ticket list toolbar
uiadmin.tickets_list.toolbar
`admin/tickets` no parameters
Appears in the button group above the ticket list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tickets_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the ticket list
uiadmin.tickets_list.before_table
`admin/tickets` no parameters
Appears immediately above the ticket table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tickets_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The department list toolbar
uiadmin.department_list.toolbar
`admin/tickets/departments` no parameters
Appears in the toolbar of the department list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.department_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the department list
uiadmin.department_list.before_table
`admin/tickets/departments` no parameters
Appears immediately above the department table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.department_list.before_table', 10, function () {
return '
Acme
';
});
```
#### Above the ticket creation form
uiadmin.tickets_edit.before_content
`admin/tickets` the customer may be empty
Appears above the form staff use to open a ticket for a customer.
Parameters 1
$userarrayThe customer pre-selected for the form. It **arrives empty** when no customer is chosen yet.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tickets_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the ticket creation form
uiadmin.tickets_edit.bottom
`admin/tickets` the customer may be empty
Appears below the same form, at the bottom of the page.
Parameters 1
$userarrayThe customer pre-selected for the form. It **arrives empty** when no customer is chosen yet.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tickets_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the department form
uiadmin.department_edit.before_content
`admin/tickets/departments` empty when creating
Appears above the department add and edit form.
Parameters 1
$detailarrayThe department being edited. It is **empty when creating**: test before reaching for an id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.department_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the department form
uiadmin.department_edit.bottom
`admin/tickets/departments` empty when creating
Appears below the same form.
Parameters 1
$detailarrayThe department being edited. It is **empty when creating**: test before reaching for an id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.department_edit.bottom', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **The privilege flag is not a gate**
>
> The privilege parameter on the ticket detail **tells you whether the viewer holds it**; it does not block your output on its own. If you would rather not show an operation button to somebody without the privilege, put the condition in **your own listener**. The real check stays in the operation on the server: hiding here is only visibility.
> **The row badge runs on every row**
>
> The list badge point is called **separately for every ticket** on the page. A listener doing a database query or an outside call inside it produces fifty queries on a fifty-row page and slows the list noticeably. Collect what you need once and read it from memory.
### Related Articles
- Support Ticket Hooks
- [Ticket View Hooks](https://dev.wisecp.com/en/ticket-view-hooks)
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
## Panel Product Screen Hooks
https://dev.wisecp.com/en/admin-product-screen-hooks
The twenty-two placement points of the product screens: the edit tabs, the list toolbars and the group, add-on and server forms.
### Overview
The placement points of the product screens live here: every tab of the product edit page, the list toolbars and the group, add-on, requirement and server forms.
On most form points the record you hold is **empty on a new record**. The list points hand you the product type: the same list serves every type from hosting to certificates.
### Reference
#### Above the product edit form
uiadmin.product_edit.before_content
`admin/products/edit` above the form
Appears at the very top of the product edit page, above the tabs.
Parameters 1
$productarrayThe product being edited.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### A new tab on the product edit page
uiadmin.product_edit.tabs
`admin/products/edit` an object, not an array
Runs once the product tabs are built. You do not return HTML: you add the tab through the object’s method.
Parameters 2
$tabobjectThe tab object.
$productarrayThe product being edited.
Return 1
voidThe return is **not used**. This point shows no HTML.
Listener PHP
```php
Hook::add('ui:admin.product_edit.tabs', 10, function ($tab, $product) {
$tab->add('acme', ['title' => 'Acme', 'content' => Acme::renderTab($product)]);
});
```
#### The top of the details tab
uiadmin.product_edit.details.top
`admin/products/edit` top of the tab
Appears above the basic detail fields of the product.
Parameters 1
$detailarrayThe active product record: type, options, language data and module data.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.details.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the details tab
uiadmin.product_edit.details.bottom
`admin/products/edit` bottom of the tab
Appears below the basic detail fields. The place to put a product setting of your own inside the form.
Parameters 1
$detailarrayThe active product record: type, options, language data and module data.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.details.bottom', 10, function ($detail) {
// Alan formun icinde: kaydetmeyi filter:product.save_data ile yakalayin.
$v = htmlspecialchars((string) ($detail['options']['acme_sku'] ?? ''));
return '
Acme SKU '
. '
';
});
```
#### The bottom of the pricing tab
uiadmin.product_edit.pricing.bottom
`admin/products/edit` the pricing tab
Appears below the price table. The place for a pricing rule or note of your own.
Parameters 1
$detailarrayThe active product record: type, options, language data and module data.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.pricing.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the add-ons tab
uiadmin.product_edit.addons.bottom
`admin/products/edit` the add-on list is text
Appears below the add-on selection of the product.
Parameters 1
$detailarrayThe active product record. The linked add-ons field is **comma-separated text**, not an array: split it to work with it.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.addons.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the automation tab
uiadmin.product_edit.automation.bottom
`admin/products/edit` module settings
Appears below the server and module settings.
Parameters 1
$detailarrayThe active product record: type, options, language data and module data.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.automation.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the other tab
uiadmin.product_edit.other.bottom
`admin/products/edit` the other tab
Appears below the remaining product settings.
Parameters 1
$detailarrayThe active product record: type, options, language data and module data.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.other.bottom', 10, function () {
return '
Acme
';
});
```
#### The very bottom of the product edit page
uiadmin.product_edit.bottom
`admin/products/edit` end of the page
Appears at the very end of the page, outside the tabs.
Parameters 1
$productarrayThe product being edited.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The product list toolbar
uiadmin.product_list.toolbar
`admin/products` the type arrives
Appears in the button group above the product list.
Parameters 1
$typestringThe product type being listed: hosting, server, software, text message, certificate or special. The same list serves every type: check this if what you add should not appear on all of them.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_list.toolbar', 10, function ($type) {
// Ayni liste her tip icin kullanilir.
if ($type !== 'hosting') return null;
return '
Acme ';
});
```
#### Above the table on the product list
uiadmin.product_list.before_table
`admin/products` the type arrives
Appears immediately above the product table.
Parameters 1
$typestringThe product type being listed: hosting, server, software, text message, certificate or special. The same list serves every type: check this if what you add should not appear on all of them.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_list.before_table', 10, function ($type) {
// Ayni liste her tip icin kullanilir.
if ($type !== 'hosting') return null;
return '
Acme ';
});
```
#### Above the product creation form
uiadmin.product_add.before_content
`admin/products` no parameters
Appears above the new product form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_add.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the product creation form
uiadmin.product_add.bottom
`admin/products` no parameters
Appears below the new product form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_add.bottom', 10, function () {
return '
Acme
';
});
```
#### The add-on list toolbar
uiadmin.product_addon_list.toolbar
`admin/products` no parameters
Appears in the toolbar of the product add-on list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_addon_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The group list toolbar
uiadmin.product_group_list.toolbar
`admin/products` no parameters
Appears in the toolbar of the product group list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_group_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The server list toolbar
uiadmin.product_server_list.toolbar
`admin/products/servers` no parameters
Appears in the toolbar of the server list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_server_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The bottom of the add-on form
uiadmin.product_addon_edit.bottom
`admin/products` empty when creating
Appears below the product add-on add and edit form.
Parameters 1
$detailarrayThe add-on being edited. It is **empty on a new record**: test before reaching for an id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_addon_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the requirement form
uiadmin.product_requirement_edit.bottom
`admin/products` empty when creating
Appears below the product requirement form.
Parameters 1
$detailarrayThe requirement being edited. It is **empty on a new record**: test before reaching for an id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_requirement_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the server form
uiadmin.product_server_edit.bottom
`admin/products/servers` empty when creating
Appears below the server add and edit form.
Parameters 1
$detailarrayThe server being edited. It is **empty on a new record**: test before reaching for an id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_server_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the server group form
uiadmin.product_server_group_edit.bottom
`admin/products/servers` empty when creating
Appears below the server group form.
Parameters 1
$detailarrayThe server group being edited. It is **empty on a new record**: test before reaching for an id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_server_group_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the group form
uiadmin.product_group_edit.before_content
`admin/products` group or category
Appears above the product group and category form.
Parameters 2
$detailarrayThe group or category being edited. It is **empty on a new record**: test before reaching for an id.
$categorystringThe category context. **Empty means a top group**, filled means a category kind: the same form does two jobs.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_group_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the group form
uiadmin.product_group_edit.bottom
`admin/products` group or category
Appears below the same form.
Parameters 2
$detailarrayThe group or category being edited. It is **empty on a new record**: test before reaching for an id.
$categorystringThe category context. **Empty means a top group**, filled means a category kind: the same form does two jobs.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.product_group_edit.bottom', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **Adding a form field does not save it**
>
> A field you put at these points is **only visible**. For the value to be kept you must catch it in the save filter; otherwise an administrator fills it in, saves, and the value quietly disappears.
> **The group form does two jobs**
>
> On the group edit points an **empty category context means a top group** while a filled one means a category kind is being edited. A listener that does not tell them apart shows a category-only field on the group form.
### Related Articles
- [Product Data and Catalogue Hooks](https://dev.wisecp.com/en/product-data-hooks)
- [Server Record Hooks](https://dev.wisecp.com/en/server-record-hooks)
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
## Panel Invoice Screen Hooks
https://dev.wisecp.com/en/admin-invoice-screen-hooks
The twenty-three placement points of the invoice, cash book and coupon screens: the invoice detail, summary cards, list toolbars and forms.
### Overview
The placement points of the invoice, cash book and coupon screens live here: the sections of the invoice detail, the list toolbars and the coupon and currency forms.
The invoice summary point hands you the arithmetic already done: the **balance left** and the **total paid**. In the cash summary each value arrives in two forms; use the raw one when you calculate.
### Reference
#### A badge or button in the invoice title
uiadmin.invoices_detail.header_actions
`admin/invoices/detail` the title area
Appears in the title row of the invoice detail. It suits its counterpart in your accounting system or a shortcut of your own.
Parameters 2
$invoicearrayThe active invoice record.
$invoice_idintThe invoice id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_detail.header_actions', 10, function () {
return '
Acme
';
});
```
#### The top of the invoice summary card
uiadmin.invoice_detail.summary_card_top
`admin/invoices/detail` the balance in hand
Appears at the very top of the summary card. The balance left and the total paid are in your hands.
Parameters 4
$invoicearrayThe active invoice record.
$invoice_idintThe invoice id.
$balancefloatThe balance left. Above zero means the invoice is still unpaid; it is filled on a partial payment too.
$total_paidfloatThe total paid so far.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoice_detail.summary_card_top', 10,
function ($invoice, $invoice_id, $balance, $total_paid) {
// Kismi odemede de bakiye dolu gelir.
if ($balance <= 0 || $total_paid <= 0) return null;
return '
Kismi odeme
';
});
```
#### The bottom of the invoice summary
uiadmin.invoices_detail.summary.bottom
`admin/invoices/detail` below the summary
Appears after the lines of the summary card.
Parameters 2
$invoicearrayThe active invoice record.
$invoice_idintThe invoice id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_detail.summary.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the payments section
uiadmin.invoices_detail.payments.top
`admin/invoices/detail` the payment list
Appears above the list of payments recorded against the invoice.
Parameters 3
$invoicearrayThe active invoice record.
$invoice_idintThe invoice id.
$paymentsarrayThe payment records of the invoice.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_detail.payments.top', 10, function () {
return '
Acme
';
});
```
#### A new tab on the invoice detail
uiadmin.invoice_detail.tabs
`admin/invoices/detail` an object, not an array
Runs once the invoice tabs are built. You do not return HTML: you add the tab through the object’s method.
Parameters 2
$tabobjectThe tab object.
$invoicearrayThe full invoice record.
Return 1
voidThe return is **not used**. This point shows no HTML.
Listener PHP
```php
Hook::add('ui:admin.invoice_detail.tabs', 10, function ($tab, $invoice) {
$tab->add('acme', 'Acme', Acme::renderTab((int) ($invoice['id'] ?? 0)));
});
```
#### The very bottom of the invoice page
uiadmin.invoices_detail.bottom
`admin/invoices/detail` end of the page
Appears at the very end of the page.
Parameters 2
$invoicearrayThe active invoice record.
$invoice_idintThe invoice id.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_detail.bottom', 10, function () {
return '
Acme
';
});
```
#### Beside the invoice list summary cards
uiadmin.invoices_list.stats
`admin/invoices` data after the filter
Appears beside the summary cards above the list. It puts a card of your own next to the core ones.
Parameters 1
$initial_statsarrayThe summary data worked out: unpaid, paid and overdue. This is the data **after the summary filter ran**: a change you made there shows up here.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_list.stats', 10, function () {
return '
Acme
';
});
```
#### Above the table on the invoice list
uiadmin.invoices_list.before_table
`admin/invoices` no parameters
Appears immediately above the invoice table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The invoice list toolbar
uiadmin.invoice_list.toolbar
`admin/invoices` no parameters
Appears in the toolbar of the invoice list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoice_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The cash book toolbar
uiadmin.invoices_cash.toolbar
`admin/money` no parameters
Appears in the toolbar of the income and expense book.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_cash.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the cash book
uiadmin.invoices_cash.before_table
`admin/money` no parameters
Appears immediately above the cash book table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_cash.before_table', 10, function () {
return '
Acme
';
});
```
#### Above the table on the recurring expense list
uiadmin.invoices_periodic_expenses.before_table
`admin/money` no parameters
Appears immediately above the recurring expense table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_periodic_expenses.before_table', 10, function () {
return '
Acme
';
});
```
#### The recurring expense toolbar
uiadmin.invoices_periodic_expenses.toolbar
`admin/money` no parameters
Appears in the toolbar of the recurring expense list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_periodic_expenses.toolbar', 10, function () {
return '
Acme
';
});
```
#### The coupon list toolbar
uiadmin.coupon_list.toolbar
`admin/money` no parameters
Appears in the toolbar of the coupon list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.coupon_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the coupon list
uiadmin.coupon_list.before_table
`admin/money` no parameters
Appears immediately above the coupon table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.coupon_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The currency list toolbar
uiadmin.currency_list.toolbar
`admin/money` no parameters
Appears in the toolbar of the currency list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.currency_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the currency list
uiadmin.currency_list.before_table
`admin/money` no parameters
Appears immediately above the currency table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.currency_list.before_table', 10, function () {
return '
Acme
';
});
```
#### Below the cash book summary
uiadmin.invoices_cash.summary.after
`admin/money` raw and formatted together
Appears below the income and expense summary.
Parameters 1
$summaryarrayThe cash summary: income, expense and balance. Each value arrives in **two forms**: a raw number for arithmetic and formatted text for the screen. Use the raw one when comparing.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_cash.summary.after', 10, function ($summary) {
// Karsilastirmada HAM degeri kullanin, bicimli metni degil.
if ((float) ($summary['balance'] ?? 0) >= 0) return null;
return '
Kasa eksi bakiyede
';
});
```
#### Above the invoice creation form
uiadmin.invoices_edit.before_content
`admin/invoices` the customer may be zero
Appears above the manual invoice form.
Parameters 1
$user_idintThe customer the invoice is for. It is **zero** when no customer is chosen yet.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the invoice creation form
uiadmin.invoices_edit.bottom
`admin/invoices` the customer may be zero
Appears below the same form.
Parameters 1
$user_idintThe customer the invoice is for. It is **zero** when no customer is chosen yet.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.invoices_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the coupon form
uiadmin.coupon_edit.before_content
`admin/money` two modes
Appears above the coupon add and edit form.
Parameters 2
$coupon_idintThe coupon id; **zero when creating**.
$isEditboolWhether this is the edit mode.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.coupon_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the coupon form
uiadmin.coupon_edit.bottom
`admin/money` two modes
Appears below the same form.
Parameters 2
$coupon_idintThe coupon id; **zero when creating**.
$isEditboolWhether this is the edit mode.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.coupon_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The coupon summary column
uiadmin.coupon_edit.summary_sidebar
`admin/money` the side column
Appears in the summary column beside the coupon form.
Parameters 1
$coupon_idintThe coupon id; zero when creating.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.coupon_edit.summary_sidebar', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **Do not calculate with the formatted value**
>
> In the cash summary every amount exists in two forms: a raw number and the **formatted text** meant for the screen. That text carries a thousands separator and a currency symbol; a listener converting it back to a number gets the wrong answer on every amount large enough to have a separator.
> **A filled balance does not mean nothing was paid**
>
> The balance left in the invoice summary is **also filled on a partial payment**. A listener assuming "a balance means no payment" treats a half-paid invoice as unpaid. Look at the total paid as well.
### Related Articles
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [Invoice Amount Hooks](https://dev.wisecp.com/en/invoice-amount-hooks)
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
## Panel Shell and Order Hooks
https://dev.wisecp.com/en/admin-shell-and-order-hooks
The twenty placement points of the panel shell, the dashboard and the order screens: the head, the body, the top menus and the order detail.
### Overview
Two different scales meet here. The **shell points** run on every page of the panel: the head, the body and the top menus. The **dashboard and order points** belong to a single screen.
The difference is cost. A heavy file placed at a shell point slows the whole panel; a point tied to one screen concerns only that screen.
### Reference
#### Adding a style to the panel
uiadmin.head.css
`admin/inc` on every page
Appears in the head section of the panel, on every page. Link a stylesheet of your own here.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe HTML you return enters the head section. ? It runs on **every page of the panel**: a heavy stylesheet here slows the whole panel down. If you need it on one screen, use a point on that screen instead.
Listener PHP
```php
Hook::add('ui:admin.head.css', 10, function () {
// It runs on EVERY page: keep it light.
return '
';
});
```
#### Adding a script to the panel
uiadmin.head.js
`admin/inc` on every page
Appears in the panel footer, on every page. Despite its name the output sits at the **end of the page**, where scripts load.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe HTML you return appears at the end of the page. ? It runs on every page of the panel. If your script throws, **the panel’s own scripts can stop too**: wrap your code in your own error handling.
Listener PHP
```php
Hook::add('ui:admin.head.js', 10, function () {
// A failure here can stop the panel's own scripts too.
return '';
});
```
#### The start of the body
uiadmin.body.begin
`admin/inc` on every page
Appears at the very start of the page body, on every page. It suits an announcement banner across the whole panel.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe HTML you return appears at the start of the body. It runs on every page; use your own container so the layout holds.
Listener PHP
```php
Hook::add('ui:admin.body.begin', 10, function () {
return '
Acme
';
});
```
#### The end of the body
uiadmin.body.end
`admin/inc` on every page
Appears at the very end of the page body. It is the right place for modals and hidden containers.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.body.end', 10, function () {
return '
Acme
';
});
```
#### An item in the create menu
uiadmin.header.create_menu
`admin/inc` the top menu
Appears in the create menu on the top bar. Put a quick-create link of your own here.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.header.create_menu', 10, function () {
return '
Acme record ';
});
```
#### An item in the help menu
uiadmin.header.help_menu
`admin/inc` the top menu
Appears in the help menu on the top bar. It suits a link to your own documentation or support.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.header.help_menu', 10, function () {
return '
Acme
';
});
```
#### The top of the dashboard
uiadmin.dashboard.top
`admin/index` top of the board
Appears at the very top of the dashboard, above the statistic cards.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.dashboard.top', 10, function () {
return '
Acme
';
});
```
#### After the statistic cards
uiadmin.dashboard.statistics.after
`admin/index` after the cards
Appears immediately after the statistic cards on the dashboard. The place to add a counter card of your own to the row.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.dashboard.statistics.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the dashboard
uiadmin.dashboard.bottom
`admin/index` end of the board
Appears at the very end of the dashboard. The place to add a panel of your own.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.dashboard.bottom', 10, function () {
return '
Acme
';
});
```
#### A badge or button in the order title
uiadmin.order_detail.header_actions
`admin/orders/detail` the title area
Appears in the title row of the order detail.
Parameters 3
$orderarrayThe order record on screen.
$order_idintThe order id.
$order_statusstringThe order status: waiting, in process, active or cancelled.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_detail.header_actions', 10, function () {
return '
Acme
';
});
```
#### The top of the order detail
uiadmin.order_detail.top
`admin/orders/detail` above the content
Appears above the order content. The place to show a warning that depends on the status.
Parameters 3
$orderarrayThe order record on screen.
$order_idintThe order id.
$order_statusstringThe order status: waiting, in process, active or cancelled.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_detail.top', 10,
function ($order, $order_id, $order_status) {
if ($order_status !== 'waiting') return null;
return '
Acme onayi bekleniyor
';
});
```
#### Adding an operation to the order items
uiadmin.order_detail.item_actions
`admin/orders/detail` two flags arrive
Appears in the operation area of the order items. Two flags beside you say which operation makes sense.
Parameters 3
$orderarrayThe full order record.
$has_pending_itemsboolWhether any service or add-on is still waiting. A false means nothing is left to provision.
$has_moduleboolWhether the order holds a service on a module. A false leaves a button acting on a remote server with nothing to do.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_detail.item_actions', 10,
function ($order, $has_pending_items, $has_module) {
// Modulsuz siparişte uzak islem butonu bosa calisir.
if (!$has_pending_items || !$has_module) return null;
return '
Acme ';
});
```
#### The very bottom of the order page
uiadmin.order_detail.bottom
`admin/orders/detail` end of the page
Appears at the very end of the page.
Parameters 3
$orderarrayThe order record on screen.
$order_idintThe order id.
$order_statusstringThe order status: waiting, in process, active or cancelled.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_detail.bottom', 10, function () {
return '
Acme
';
});
```
#### The order list toolbar
uiadmin.order_list.toolbar
`admin/orders` no parameters
Appears in the toolbar of the order list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the order list
uiadmin.order_list.before_table
`admin/orders` no parameters
Appears immediately above the order table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_list.before_table', 10, function () {
return '
Acme
';
});
```
#### Above the order creation form
uiadmin.order_create.before_content
`admin/orders` no parameters
Appears above the manual order form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_create.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the order creation form
uiadmin.order_create.bottom
`admin/orders` no parameters
Appears below the same form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.order_create.bottom', 10, function () {
return '
Acme
';
});
```
#### The top of the domain pricing screen
uiadmin.domain_pricing.top
`admin/domains` no parameters
Appears above the extension price table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.domain_pricing.top', 10, function () {
return '
Acme
';
});
```
#### The bottom of the domain pricing screen
uiadmin.domain_pricing.bottom
`admin/domains` no parameters
Appears below the extension price table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.domain_pricing.bottom', 10, function () {
return '
Acme
';
});
```
#### The document list toolbar
uiadmin.domain_doc_list.toolbar
`admin/domains` no parameters
Appears in the toolbar of the extension document requirement list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.domain_doc_list.toolbar', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **Shell points run on every page of the panel**
>
> The style and script points are not limited to one screen: whatever page an administrator opens, your output goes into it. A heavy file, or a script calling an outside service on every load, slows **the whole panel**. If what you add belongs to one screen, use that screen’s own point.
> **A failure in your script can stop the panel’s scripts**
>
> Code you add at the end of the page runs beside the panel’s own. An uncaught error halts script execution in the browser: what goes unresponsive is not your panel but **the screen the administrator is using**. Wrap your code in your own error handling.
### Related Articles
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
- Order Hooks
- [Panel Analytics Hooks](https://dev.wisecp.com/en/admin-analytics-hooks)
## Panel Content Screen Hooks
https://dev.wisecp.com/en/admin-content-screen-hooks
The twenty-two placement points of the content, message, notification and language screens: forms, lists and toolbars.
### Overview
The placement points of the site content, contact messages, notification templates and languages live here.
One thing runs through the content screens: **the same screen serves several types**. Pages, contracts, news, articles and references share one form; the message list serves five folders. Check the type if what you add should not appear on all of them.
### Reference
#### After the page title
uiadmin.content.page_title.after
`admin/manage-website` on many pages
Appears after the title on the content management pages. The controller name tells you which page you are on.
Parameters 1
$controllerstringThe name of the active controller. The hook runs on several pages: without a check your output appears on all of them.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.content.page_title.after', 10, function ($controller) {
// Kanca birden cok sayfada calisir.
if ($controller !== 'pages') return null;
return '
Acme ';
});
```
#### Above the content form
uiadmin.content_edit.before_content
`admin/manage-website` five content types
Appears above the content edit form.
Parameters 2
$page_typestringThe content type: page, contract, news, article or reference. The same screen serves five types: check this if what you add should not appear on all of them.
$detailarrayThe content record being edited. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.content_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the content form
uiadmin.content_edit.bottom
`admin/manage-website` five content types
Appears below the same form. The place to add a metadata field of your own.
Parameters 2
$page_typestringThe content type: page, contract, news, article or reference. The same screen serves five types: check this if what you add should not appear on all of them.
$detailarrayThe content record being edited. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.content_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The content list toolbar
uiadmin.content_list.toolbar
`admin/manage-website` the screen links
Appears in the toolbar of the content list. The links of the screen itself are in your hands too.
Parameters 2
$page_typestringThe content type: page, contract, news, article or reference. The same screen serves five types: check this if what you add should not appear on all of them.
$linksarrayThe links of the screen: controller, add, categories and contracts.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.content_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the content list
uiadmin.content_list.before_table
`admin/manage-website` above the table
Appears immediately above the content table.
Parameters 1
$page_typestringThe content type: page, contract, news, article or reference. The same screen serves five types: check this if what you add should not appear on all of them.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.content_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The bottom of the content category form
uiadmin.content_category_edit.bottom
`admin/manage-website` two category types
Appears below the form of the blog and reference categories.
Parameters 2
$category_typestringThe category type: article or reference.
$detailarrayThe category being edited. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.content_category_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the slide form
uiadmin.slide_edit.bottom
`admin/manage-website` empty when creating
Appears below the home page slide form.
Parameters 1
$detailarrayThe slide being edited. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.slide_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### The message action area
uiadmin.messages_detail.actions
`admin/manage-website/messages` no parameters
Appears in the action area of a contact message.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.messages_detail.actions', 10, function () {
return '
Acme
';
});
```
#### The message toolbar
uiadmin.messages_detail.message.toolbar
`admin/manage-website/messages` no parameters
Appears in the toolbar of the message itself.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.messages_detail.message.toolbar', 10, function () {
return '
Acme
';
});
```
#### The message reply form toolbar
uiadmin.messages_detail.reply_form.toolbar
`admin/manage-website/messages` no parameters
Appears in the toolbar of the reply form.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.messages_detail.reply_form.toolbar', 10, function () {
return '
Acme
';
});
```
#### Below the message editor
uiadmin.messages_detail.reply_editor.after
`admin/manage-website/messages` no parameters
Appears immediately below the reply editor.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.messages_detail.reply_editor.after', 10, function () {
return '
Acme
';
});
```
#### The message list toolbar
uiadmin.messages_list.toolbar
`admin/manage-website/messages` the folder arrives
Appears in the toolbar of the contact message list.
Parameters 1
$folderstringThe open folder: unread, read, replied, spam or trash. The same toolbar serves all five folders.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.messages_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The notification template list toolbar
uiadmin.notification_list.toolbar
`admin/notifications` grouped template list
Appears in the toolbar of the notification template list.
Parameters 1
$templatesarrayEvery template group, each carrying its name and items. It is not a flat list but a **two-level** structure: walk the groups and look inside.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.notification_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the template list
uiadmin.notification_list.before_table
`admin/notifications` grouped template list
Appears immediately above the template table.
Parameters 1
$templatesarrayEvery template group, each carrying its name and items. It is not a flat list but a **two-level** structure: walk the groups and look inside.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.notification_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The bottom of the template list
uiadmin.notification_list.bottom
`admin/notifications` grouped template list
Appears at the very bottom of the template list.
Parameters 1
$templatesarrayEvery template group, each carrying its name and items. It is not a flat list but a **two-level** structure: walk the groups and look inside.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.notification_list.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the template form
uiadmin.notification_edit.before_content
`admin/notifications` group and key
Appears above the notification template edit form.
Parameters 3
$nTemplatearrayThe template being edited: its status, language contents and recipient settings.
$nGroupstringThe group of the template.
$nKeystringThe key of the template. Test the group and the key together to recognise your own template.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.notification_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the template form
uiadmin.notification_edit.bottom
`admin/notifications` group and key
Appears below the same form. The place to show a list of your own variables.
Parameters 3
$nTemplatearrayThe template being edited: its status, language contents and recipient settings.
$nGroupstringThe group of the template.
$nKeystringThe key of the template. Test the group and the key together to recognise your own template.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.notification_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the notification settings form
uiadmin.notification_settings.before_form
`admin/notifications` the shared shell code
Appears above the notification shell settings.
Parameters 1
$settingsarrayThe current settings: per-language header, body and footer code, and the logo paths. That code is the shell of **every** notification: a change here reaches every message sent.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.notification_settings.before_form', 10, function () {
return '
Acme
';
});
```
#### The language list toolbar
uiadmin.language_list.toolbar
`admin/languages` no parameters
Appears in the toolbar of the language list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.language_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the language list
uiadmin.language_list.before_table
`admin/languages` no parameters
Appears immediately above the language table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.language_list.before_table', 10, function () {
return '
Acme
';
});
```
#### Above the language form
uiadmin.language_edit.before_content
`admin/languages` empty when creating
Appears above the language add and edit form.
Parameters 1
$detailarrayThe language being edited: its name, status, whether it is local, and its writing direction. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.language_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the language form
uiadmin.language_edit.bottom
`admin/languages` empty when creating
Appears below the same form.
Parameters 1
$detailarrayThe language being edited: its name, status, whether it is local, and its writing direction. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.language_edit.bottom', 10, function () {
return '
Acme
';
});
```
### Pitfalls
> **One screen serves many types**
>
> The content form serves five separate types, the message list five folders, and the page title point many controllers. A listener that outputs without checking the type shows a **blog field** to an administrator editing a contract.
> **The template list has two levels**
>
> The list at the notification template points is not flat: first come the **groups**, then the items of each group. A listener walking it as one level never sees the items at all.
### Related Articles
- [Notification Hooks](https://dev.wisecp.com/en/notification-hooks)
- [Language and Translation Hooks](https://dev.wisecp.com/en/language-and-translation-hooks)
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
## Panel Settings and Tool Hooks
https://dev.wisecp.com/en/admin-settings-and-tool-hooks
The thirty-seven placement points of the settings, staff, module, automation and tool screens: tab points, forms and toolbars.
### Overview
The placement points of the settings, staff, module, automation and tool screens live here.
What marks this group out is **how many tab points it holds**: the general, security, tax, account, automation and staff settings each carry their own. All of them hand you an object rather than HTML, and the tab is added through a method call.
### Reference
#### A new tab in the general settings
uiadmin.settings.tabs
`admin/settings` an object, not an array
Runs once the general settings tabs are built.
Parameters 1
$tabobjectThe tab object; add a tab through its method.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.settings.tabs', 10, function ($tab) {
$tab->add('acme', 'Acme', Acme::renderSettings());
});
```
#### A new tab in the security settings
uiadmin.security_settings.tabs
`admin/settings` an object, not an array
Runs once the security settings tabs are built.
Parameters 1
$tabobjectThe tab object; add a tab through its method.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.security_settings.tabs', 10, function ($tab) {
$tab->add('acme-sec', 'Acme', Acme::renderSecurity());
});
```
#### A new tab in the tax settings
uiadmin.taxation_settings.tabs
`admin/settings` an object, not an array
Runs once the tax settings tabs are built.
Parameters 1
$tabobjectThe tab object; add a tab through its method.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.taxation_settings.tabs', 10, function ($tab) {
$tab->add('acme-tax', 'Acme', Acme::renderTax());
});
```
#### A new tab in the account settings
uiadmin.account_settings.tabs
`admin/settings` an object, not an array
Runs once the tabs of an administrator’s own account settings are built.
Parameters 2
$tabobjectThe tab object; add a tab through its method.
$udataarrayThe signed-in administrator’s data.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.account_settings.tabs', 10, function ($tab, $udata) {
$tab->add('acme-me', 'Acme', Acme::renderMyPrefs((int) ($udata['id'] ?? 0)));
});
```
#### A new tab in the automation settings
uiadmin.automation_settings.tabs
`admin/automation` an object, not an array
Runs once the automation settings tabs are built.
Parameters 1
$tabobjectThe tab object; add a tab through its method.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.automation_settings.tabs', 10, function ($tab) {
$tab->add('acme-cron', 'Acme', Acme::renderCronSettings());
});
```
#### A new tab on the staff form
uiadmin.staff_edit.tabs
`admin/staff` an object, not an array
Runs once the staff edit tabs are built.
Parameters 2
$tabobjectThe tab object; add a tab through its method.
$detailarrayThe staff record. ? **There is no id when creating**: test before adding a tab that depends on one.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.staff_edit.tabs', 10, function ($tab, $detail) {
// Ekleme modunda kimlik YOK.
if (!($detail['id'] ?? 0)) return;
$tab->add('acme', 'Acme', Acme::renderStaffTab((int) $detail['id']));
});
```
#### A new tab in the action logs
uiadmin.tools_actions_list.tabs
`admin/tools` a different method
Runs once the action log tabs are built.
Parameters 1
$tabobjectThe tab object. ? On this screen a tab is added through **a different method**; calling the one used at the sibling points does nothing here.
Return 1
voidThe return is **not used**. This point shows no HTML: the tab is added through the object’s method.
Listener PHP
```php
Hook::add('ui:admin.tools_actions_list.tabs', 10, function ($tab) {
// Bu ekranda metot farkli.
$tab->set('acme', 'Acme', Acme::renderActions());
});
```
#### The bottom of the general settings
uiadmin.settings.bottom
`admin/settings` no parameters
Appears at the very bottom of the general settings page.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.settings.bottom', 10, function () {
return '
Acme
';
});
```
#### The staff list toolbar
uiadmin.staff_list.toolbar
`admin/staff` no parameters
Appears in the toolbar of the staff list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.staff_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the staff list
uiadmin.staff_list.before_table
`admin/staff` no parameters
Appears immediately above the staff table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.staff_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The privilege list toolbar
uiadmin.privilege_list.toolbar
`admin/staff` no parameters
Appears in the toolbar of the privilege group list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.privilege_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the table on the privilege list
uiadmin.privilege_list.before_table
`admin/staff` no parameters
Appears immediately above the privilege table.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.privilege_list.before_table', 10, function () {
return '
Acme
';
});
```
#### The add-on list toolbar
uiadmin.tools_addons_list.toolbar
`admin/tools` no parameters
Appears in the toolbar of the add-on list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tools_addons_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### The task list toolbar
uiadmin.tools_tasks_list.toolbar
`admin/tools` no parameters
Appears in the toolbar of the panel task list.
Parameters 0
—It takes no parameters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tools_tasks_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the staff form
uiadmin.staff_edit.before_content
`admin/staff` empty when creating
Appears above the staff add and edit form.
Parameters 1
$detailarrayThe staff record being edited. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.staff_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the staff form
uiadmin.staff_edit.bottom
`admin/staff` empty when creating
Appears below the same form.
Parameters 1
$detailarrayThe staff record being edited. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.staff_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the privilege form
uiadmin.privilege_edit.before_content
`admin/staff` empty when creating
Appears above the privilege group form.
Parameters 1
$detailarrayThe privilege record: its name and permissions. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.privilege_edit.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the privilege form
uiadmin.privilege_edit.bottom
`admin/staff` empty when creating
Appears below the same form.
Parameters 1
$detailarrayThe privilege record: its name and permissions. It is **empty when creating**.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.privilege_edit.bottom', 10, function () {
return '
Acme
';
});
```
#### Above the add-on settings
uiadmin.addon_configure.before
`admin/modules` on every add-on
Appears on the add-on settings page, above the module’s own content.
Parameters 2
$moduleobjectThe module instance; you may query its methods.
$module_dataarrayThe record and configuration of the module: name, version and settings. The settings can hold an API key: keep it off the screen.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.addon_configure.before', 10, function ($module, $module_data) {
// Kanca HER eklentinin ayar sayfasinda calisir: kendinizinkini secin.
if (($module_data['name'] ?? '') !== 'Acme') return null;
return '
Acme
';
});
```
#### Below the add-on settings
uiadmin.addon_configure.after
`admin/modules` on every add-on
Appears on the same page, below the module’s content.
Parameters 2
$moduleobjectThe module instance; you may query its methods.
$module_dataarrayThe record and configuration of the module: name, version and settings. The settings can hold an API key: keep it off the screen.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.addon_configure.after', 10, function ($module, $module_data) {
// Kanca HER eklentinin ayar sayfasinda calisir: kendinizinkini secin.
if (($module_data['name'] ?? '') !== 'Acme') return null;
return '
Acme
';
});
```
#### Above the module settings
uiadmin.module_settings.before
`admin/modules` on every module
Appears above the content on the module configuration page.
Parameters 2
$moduleobjectThe module being configured.
$module_dataarrayThe data and configuration of the module.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.module_settings.before', 10, function () {
return '
Acme
';
});
```
#### Below the module settings
uiadmin.module_settings.after
`admin/modules` on every module
Appears below the content on the same page.
Parameters 2
$moduleobjectThe module being configured.
$module_dataarrayThe data and configuration of the module.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.module_settings.after', 10, function () {
return '
Acme
';
});
```
#### Above the module page
uiadmin.module_page.before
`admin/modules` the instance may be empty
Appears above the content on a module’s own management page.
Parameters 2
$module_keystringThe key of the active module.
$moduleobjectThe admin area instance of the module. ? On some paths it **arrives empty**: test before calling a method.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.module_page.before', 10, function ($module_key, $module) {
// Ornek BOS gelebilir.
if (!$module) return null;
return Acme::renderModuleBanner($module_key);
});
```
#### Below the module page
uiadmin.module_page.after
`admin/modules` the instance may be empty
Appears below the content on the same page.
Parameters 2
$module_keystringThe key of the active module.
$moduleobjectThe admin area instance of the module. ? On some paths it **arrives empty**: test before calling a method.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.module_page.after', 10, function ($module_key, $module) {
// Ornek BOS gelebilir.
if (!$module) return null;
return Acme::renderModuleBanner($module_key);
});
```
#### The module list toolbar
uiadmin.module_list.toolbar
`admin/modules` the group arrives
Appears in the toolbar of the module list.
Parameters 1
$group_namestringThe active module group: mail, text message, payment, registrar, product or fraud check. The same list serves every group.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.module_list.toolbar', 10, function () {
return '
Acme
';
});
```
#### Above the grid on the module list
uiadmin.module_list.before_grid
`admin/modules` above the grid
Appears above the module cards.
Parameters 2
$modulesarrayThe data of the modules being listed.
$group_namestringThe active module group.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.module_list.before_grid', 10, function () {
return '
Acme
';
});
```
#### Above the theme settings
uiadmin.theme_settings.before
`admin/settings` the theme instance
Appears above the content on the theme configuration page.
Parameters 1
$themeobjectThe theme being configured.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.theme_settings.before', 10, function () {
return '
Acme
';
});
```
#### Below the theme settings
uiadmin.theme_settings.after
`admin/settings` the theme instance
Appears below the content on the same page.
Parameters 1
$themeobjectThe theme being configured.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.theme_settings.after', 10, function () {
return '
Acme
';
});
```
#### The bottom of the automation board
uiadmin.automation_dashboard.bottom
`admin/automation` the queue counters
Appears at the very bottom of the scheduled task board.
Parameters 1
$statsarrayThe board data: system state and queue counters.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.automation_dashboard.bottom', 10, function () {
return '
Acme
';
});
```
#### The bottom of the automation system tab
uiadmin.automation_settings.system_tab.bottom
`admin/automation` carries a secret key
Appears below the scheduled task system settings.
Parameters 1
$configarrayThe whole task configuration. ? It holds the **secret key** that guards the cron address. Whoever sees it can trigger the tasks from outside: keep it off the screen and out of your logs.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.automation_settings.system_tab.bottom', 10, function () {
return '
Acme
';
});
```
#### Adding an operation to a task card
uiadmin.automation_task_card.actions
`admin/automation` per task
Appears in the operation area of the scheduled task cards, **separately for every task**.
Parameters 1
$taskarrayThe data of one task: its name, frequency, pending and failed counts, and whether it is switched off. The hook runs per task: keep heavy work out of it.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.automation_task_card.actions', 10, function () {
return '
Acme
';
});
```
#### The analytics overview toolbar
uiadmin.analytics.overview.toolbar
`admin/analytics` section and range
Appears in the toolbar of the report overview page.
Parameters 2
$sectionstringThe active section: clients, services or support.
$rangearrayThe active date range.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.analytics.overview.toolbar', 10, function () {
return '
Acme
';
});
```
#### The bottom of an analytics report
uiadmin.analytics.report.bottom
`admin/analytics` the range may be empty
Appears at the very bottom of a report page.
Parameters 2
$reportstringThe active report key.
$rangearrayThe active date range. It **arrives empty** on reports that use no date range.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.analytics.report.bottom', 10, function () {
return '
Acme
';
});
```
#### Adding an operation to the distribution card
uiadmin.analytics.distribution_card.actions
`admin/analytics` the distribution card
Appears in the operation area of the distribution chart.
Parameters 1
$entitystringWhat is distributed: clients, services or tickets.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.analytics.distribution_card.actions', 10, function () {
return '
Acme
';
});
```
#### Above the import wizard
uiadmin.tools_imports_wizard.before_content
`admin/tools` the platform list
Appears above the import wizard.
Parameters 1
$platformsarrayThe import platforms installed.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.tools_imports_wizard.before_content', 10, function () {
return '
Acme
';
});
```
#### Below the licence details
uiadmin.help_license.after
`admin/tools` licence details
Appears below the licence information screen.
Parameters 1
$license_infoarrayThe licence details: owner, product, the address it is locked to and its dates.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.help_license.after', 10, function () {
return '
Acme
';
});
```
#### Above the updates screen
uiadmin.help_updates.before_content
`admin/tools` may be false
Appears above the version update screen.
Parameters 1
$new_versionmixedDetails of the new version found. With no new version it arrives as **false** rather than an array: test before reading a field.
Return 1
string|nullThe **HTML you return appears**. With several listeners the outputs are appended one after another in priority order. Empty text, `null` and `false` are skipped, so return `null` when you have nothing to add. The output enters the page unescaped — clean anything coming from outside yourself.
Listener PHP
```php
Hook::add('ui:admin.help_updates.before_content', 10, function ($new_version) {
// Yeni surum yoksa dizi degil YANLIS gelir.
if (!is_array($new_version)) return null;
return '
Acme uyumluluk notu
';
});
```
### Pitfalls
> **The action log screen uses a different tab method**
>
> Every tab point looks alike, but the **action log screen uses another method**. Code copied from a sibling point quietly does nothing here: no error appears, and neither does the tab.
> **The automation configuration carries a secret key**
>
> The configuration array on the system tab holds the **secret key** that guards the scheduled task address. Printing it to the screen or copying it into your own store makes the tasks triggerable from outside.
### Related Articles
- [Panel Staff and Privilege Hooks](https://dev.wisecp.com/en/admin-staff-hooks)
- [Module Installation Hooks](https://dev.wisecp.com/en/module-installation-hooks)
- [Management Panel Hooks](https://dev.wisecp.com/en/hooks-in-the-management-panel)
# Hooks / Customer Account
## Customer Account Hooks
https://dev.wisecp.com/en/customer-account-hooks
The 103 hooks about the customer account itself: signing up, signing in, verifying, blocking, sub-accounts and affiliates.
### Overview
This domain carries the account **itself**: its opening, its sign-in, its verification, its blocking, its deletion. The screens a customer sees are a domain of their own.
Some of these hooks fire **in the management panel**, because an operator can change an account too. So when writing a listener, the answer to "who did this" is not always the customer.
### Reference
#### The account's life
- **action:user.created**: An account was opened. The return is ignored.
- **action:user.updated**: Account details changed. The return is ignored.
- **action:user.status_changed**: The account status changed. The return is ignored.
- **action:user.account_blocked**: The account was blocked, or unblocked. The return is ignored.
- **action:user.deleted**: The account was deleted. The return is ignored.
- **action:user.deleted_dormant**: A long-dormant account was deleted on its own. The return is ignored.
#### Sign-in and security
- **action:user.logged_in**: A sign-in happened. The return is ignored.
- **action:user.login_failed**: A sign-in attempt failed. The return is ignored.
- **action:user.logged_in_as**: A staff member entered a customer account. The return is ignored.
- **action:user.password_changed**: The password changed. The return is ignored.
- **action:user.two_factor_changed**: Two-step verification was switched on or off. The return is ignored; by here the change is already saved.
- **action:user.session_revoked**: A session was ended. The return is ignored.
- **action:user.account_switched**: The customer switched to another account. The return is ignored; the session is already written.
#### Gates
Eighteen gates stand in front of every weighty account action. They share one contract: a non-empty string stops the action. An empty return — `null` or `''` — lets it through.
- **gate:user.create**: Opening an account. A filled return stops it, and that text becomes the error.
- **gate:user.login**: Signing in — after the password checked out. A filled return stops it; a string and `['message' => '…']` are both taken.
- **gate:user.login_as**: A staff member entering a customer account. A filled return stops it.
- **gate:user.delete**: Deleting an account. A filled return stops it, and the delete answers `false`.
- **gate:user.block**: Blocking an account. A filled return stops it.
- **gate:user.add_funds**: Adding funds — before the invoice is issued. A filled return stops it, and the text reaches the customer.
- **gate:user.email_change**: Changing the e-mail address. A filled return stops it.
- **gate:user.two_factor_disable**: Switching two-step verification off. A filled return stops it; a string and `['message' => '…']` are both taken.
- **gate:user.affiliate_enroll**: Joining the affiliate programme. A filled return stops it, and no record is opened.
- **gate:user.affiliate_withdrawal**: An affiliate payout request. A filled return stops it.
- **gate:user.gdpr_process**: Processing a data request. A filled return stops it.
- **gate:user.subuser_invite**: Inviting a sub-account. A filled return stops it, and the text reaches the customer.
#### Filters
These eight do **not** share one contract. Three shapes stand side by side, so read the return of the one you are writing for.
- **filter:user.required_fields**: The required fields on signing up and on the profile. Return an array; every listener's return is merged in.
- **filter:user.login_resolve**: Which account the entered identity resolves to. The value changes by reference; the return is not used.
- **filter:user.password_verify**: The password check. Returning `true` counts the password as good; every other return is ignored.
- **filter:user.login_redirect**: Where a sign-in lands. The value changes by reference; the return is not used.
- **filter:user.add_funds_amount**: The amount being added. The value changes by reference; the return is not used.
- **filter:custom_field.save_value**: The value a custom field saves. The value changes by reference; the return is not used.
- **filter:custom_field.load_value**: The value a custom field loads. The value changes by reference; the return is not used.
- **filter:user.verification_fields**: The fields on a verification document. The fields change by reference; the return is ignored.
#### Example
```php
// A GATE: no account from a blocked country.
Hook::add('gate:user.create', 10, function ($data) {
$cc = strtoupper((string) ($data['country'] ?? ''));
if (Acme::blockedCountry($cc)) return 'We take no sign-ups from there.';
return null;
});
// AN EVENT: put the new account on the marketing list.
Hook::add('action:user.created', 10, function ($user_id, $data) {
Crm::subscribe((int) $user_id, (string) ($data['email'] ?? ''));
});
```
### Pitfalls
> **Both the customer and an operator change an account**
>
> Most hooks here fire from **two places**: the customer's own screen and the management panel. Writing a gate to say "the customer cannot do this" stops **the operator** as well. Where you need to tell them apart, read the actor the hook hands you.
> **The sign-in gate does not check the password**
>
> The sign-in gate runs **after** the credentials check. The work there is not checking a password but stopping for another reason. To touch the password check itself, a filter of its own exists.
> **Sub-accounts and switching blur the identity**
>
> A customer can enter another account as a **sub-user**. The person signed in and the account being worked on are then **different**. Use the account id the hook hands you; an id read from the session points at the wrong person after a switch.
> **The delete hook is a point of no return**
>
> Deleting an account takes its records with it. By the time the delete **event** fires the work is done; gather what you need at **the gate** instead. The gate is earlier, and it can stop the action where that is wanted.
### Related Articles
- [Customer Site Data and Gates](https://dev.wisecp.com/en/customer-site-data-and-gates)
- [Service Lifecycle Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
## Partner Programme Hooks
https://dev.wisecp.com/en/affiliate-hooks
The four hooks over enrolment, commissions, referral clicks and payout requests.
### Overview
The four moments of the partner programme: a customer **joins**, their link is **clicked**, a sale raises a **commission**, and they **ask to be paid**.
One distinction to hold from the start: the id of the partner record and the id of the customer are **separate numbers**, and the hooks carry both.
### Reference
#### Following an enrolment
actionuser.affiliate_activated
`ClientAffiliate` at enrolment
Runs after a customer joins the partner programme.
Parameters 2
$user_idintThe id of the account that joined.
$aff_idintThe id of the partner record created. This is a **different** number from the customer id; the sibling hooks carry both separately.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.affiliate_activated', 10, function ($user_id, $aff_id) {
// Two different ids: the partner record is not the customer number.
Acme::openPartnerDashboard($user_id, $aff_id);
});
```
#### Following a commission being made
actionuser.affiliate_commission_created
`ClientAffiliate` sale and renewal
Runs after a commission is credited to a partner. Both first sales and renewals land here.
Parameters 4
$affiliate_idintThe partner record receiving it.
$servicearrayThe service behind it: amount, currency and owner.
$transaction_typestring`sale` for a first sale, `renewal` for a renewal. On renewals the commission recurs every period: mind the difference if you hand out a one-off reward.
$commissionfloatThe commission worked out.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.affiliate_commission_created', 10,
function ($affiliate_id, $service, $transaction_type, $commission) {
// On renewals the commission recurs every period.
if ($transaction_type === 'sale') Acme::rewardFirstSale($affiliate_id);
});
```
#### Following a referral click
actionuser.affiliate_referral_clicked
`ClientAffiliate` on every click
Runs when a partner link is clicked. It fires on **every** click, with or without a sale, with or without a logged-in visitor.
Parameters 2
$ownerIdintThe customer id of the partner; this is the attribution key.
$contextarrayThe click context: the partner record, where the visitor came from and their address. The referring address **can be empty**, and it may count as personal data, so mind how long you keep it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.affiliate_referral_clicked', 10, function ($ownerId, $context) {
// It runs on every click: keep heavy work out of here.
Acme::countClick($ownerId);
});
```
#### Following a payout request
actionuser.affiliate_withdrawal_requested
`ClientAffiliate` nothing paid yet
Runs when a partner asks for their earnings. **Nothing has been paid**: the record opens in a waiting state.
Parameters 6
$uidintThe customer asking.
$affIdintThe partner record, **not** the customer id.
$amountfloatThe amount asked for; it matches what was written exactly.
$cidintThe currency of the partner.
$gatewaystringThe payout channel chosen.
$widintThe request record created; always above zero.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.affiliate_withdrawal_requested', 10,
function ($uid, $affId, $amount, $cid, $gateway, $wid) {
// Nothing was PAID: the request opened in a waiting state.
Acme::queuePayout($wid, $affId, $amount, $gateway);
});
```
### Pitfalls
> **The partner record and the customer are separate numbers**
>
> The payout hook carries both the customer id and the partner record, and **they are not the same number**. Taking the partner record for a customer id books the earnings against the wrong account.
> **On renewals the commission recurs every period**
>
> The commission hook fires on the first sale and on every renewal. If you hand out a one-off reward, check the transaction type; otherwise the same customer earns it again each month.
### Related Articles
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Balance and Payment Preference Hooks
https://dev.wisecp.com/en/balance-hooks
The four hooks over the wallet, balance adjustments and the auto-payment chain.
### Overview
Money enters or leaves a customer wallet four ways: a top-up request, credit from an invoice, a manual adjustment by an administrator, and a change in the auto-payment chain.
Currency is the trap here: a balance is kept in its own currency while an invoice may be in another. Check which one an amount is in before carrying it anywhere.
### Reference
#### Following the auto-payment chain
actionuser.autopay_changed
`AccountCards` head of the chain
Runs when the auto-payment chain of an account changes.
Parameters 2
$uidintThe owner of the account.
$autopayCtxarrayThe current head of the chain. When the chain empties this **arrives empty**: the account has no card left to pay with and renewals will fail.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.autopay_changed', 10, function ($uid, $autopayCtx) {
// An empty chain means renewals will fail.
if (!($autopayCtx['backup_card'] ?? null)) Acme::warnNoCard($uid);
});
```
#### Following credit reaching the balance
actionuser.balance_credited
`Invoices` after conversion
Runs when credit from an invoice reaches a customer balance.
Parameters 4
$user_idintThe customer whose balance grew.
$amountfloatThe amount credited, **in the balance currency** and after conversion. It need not match the invoice total: the invoice may be in another currency.
$currencyintThe balance currency.
$invoicearrayThe source invoice.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.balance_credited', 10, function ($user_id, $amount, $currency, $invoice) {
// The amount is in the balance currency: do not mix it with the invoice one.
Acme::ledgerCredit($user_id, $amount, $currency);
});
```
#### Following a balance adjustment
actionuser.credit_adjusted
`AdminUsers` two directions
Runs when an administrator adjusts a balance by hand.
Parameters 5
$user_idintThe customer whose balance moved.
$typestringWhich way: `up` credit, `down` debit.
$amountfloatThe adjustment amount.
$new_balancefloatThe balance after the change.
$cidintThe balance currency.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.credit_adjusted', 10,
function ($user_id, $type, $amount, $new_balance, $cid) {
Acme::ledgerAdjust($user_id, $type, $amount, $new_balance);
});
```
#### Following a top-up request
actionuser.funds_added
`AccountBalance` the net amount
Runs when a customer asks to top up their wallet.
Parameters 3
$uidintThe owner of the wallet.
$amountfloatThe **net** amount asked for. Tax and gateway commission are **not included**: what the customer pays is higher. Do not book this number as the amount paid.
$fundsCtxarrayContext: which surface the request came from and the minimum.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.funds_added', 10, function ($uid, $amount, $fundsCtx) {
// The NET amount: tax and commission are not in it.
Acme::noteTopupIntent($uid, $amount);
});
```
### Pitfalls
> **The balance amount is not the invoice amount**
>
> What reaches a balance arrives **in the balance currency** and after conversion. It need not equal the invoice total; treating them as one number produces a gap in your books.
> **The top-up amount is the net amount**
>
> The amount in the top-up hook is **net**: tax and gateway commission are not in it. What the customer pays is higher, so do not record this number as the sum collected.
### Related Articles
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Account Security Hooks
https://dev.wisecp.com/en/account-security-hooks
The nine hooks over verification, password resets, sign-outs and access.
### Overview
Every step that guards the identity of an account lives here: email and phone verification, the security question, password resets, login codes and sign-outs.
Two gates stand out. The password gate hands you the **raw password**; only check it. The access gate works the other way round from the rest: a filled return **skips** the built-in checks.
### Reference
#### Following an email change
actionuser.email_changed
`AccountUsers` a verified address
Runs after the email address of an account changes. The new address is **verified**.
Parameters 3
$uidintThe account owner.
$oldEmailstringThe previous address.
$newEmailstringThe new, verified address.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.email_changed', 10, function ($uid, $oldEmail, $newEmail) {
// Tell the old address too: if the account was taken, that is the only warning path.
Acme::alertOldAddress($oldEmail, $newEmail);
});
```
#### Following an email verification
actionuser.email_verified
`AccountUsers` at verification
Runs after a customer verifies their email address.
Parameters 1
$user_idintThe customer whose address was verified.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.email_verified', 10, function ($user_id) {
Acme::unlockOnboarding($user_id);
});
```
#### Following a phone verification
actionuser.phone_verified
`AccountUsers` international form
Runs after a customer verifies their phone number.
Parameters 2
$uidintThe customer whose number was verified.
$phonestringThe verified number as stored, in **international form**. The country code leads it; do not expect a local format.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.phone_verified', 10, function ($uid, $phone) {
// The number is in international form.
Acme::enableSmsAlerts($uid, $phone);
});
```
#### Following a security question change
actionuser.security_question_changed
`AccountUsers` always the login id
Runs when the security question of an account is set or removed.
Parameters 2
$user_idintThe member whose question changed. This is **always the person signed in**: a sub-user cannot change somebody else’s question.
$has_questionboolTrue when a question is now set; false when the question **and its answer** were removed together.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.security_question_changed', 10, function ($user_id, $has_question) {
// Removal comes through this hook too.
if (!$has_question) Acme::warnWeakerRecovery($user_id);
});
```
#### Following a password reset request
actionuser.password_reset_requested
`Auth` two account types
Runs when a password reset is requested. Both customer and administrator accounts pass here.
Parameters 3
$userIdintThe account the request opened for.
$typestringThe account type: `member` or `admin`. Administrator resets matter far more; keep the two apart.
$emailstringThe address it was requested from, confirmed to match the account.
Return 1
voidThe return is ignored. What your listener returns **cannot change** the reset response.
Listener PHP
```php
Hook::add('action:user.password_reset_requested', 10, function ($userId, $type, $email) {
// An administrator reset matters far more.
if ($type === 'admin') Acme::alertSecurityTeam($userId, $email);
});
```
#### Following a sign-out
actionuser.logged_out
`Auth` session captured first
Runs when a session is closed.
Parameters 2
$dataarrayThe session of the person leaving, **captured before the sign-out**. With no session it **arrives empty**: look before reaching for an id.
$typestringThe sign-out type: `admin` or `member`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.logged_out', 10, function ($data, $type) {
// With no session the array arrives EMPTY.
if (!($data['id'] ?? 0)) return;
Acme::closeSession((int) $data['id'], $type);
});
```
#### Following a login code being sent
actionuser.login_code_issued
`Auth` the code is not passed
Runs when a one-time login code goes out.
Parameters 3
$userIdintThe member the code went to.
$channelstringThe delivery channel.
$expiryintWhen the code stops working. The code **itself is not passed**, deliberately: handing it to a listener would spread it to a second place.
Return 1
voidThe return is ignored; it cannot change the response.
Listener PHP
```php
Hook::add('action:user.login_code_issued', 10, function ($userId, $channel, $expiry) {
// The code itself is deliberately withheld.
Acme::noteLoginAttempt($userId, $channel);
});
```
#### Following a device being trusted
actionuser.device_trusted
`Auth` the trust token is not passed
Runs when an account ticks "trust this device" on the two-factor screen and the browser is remembered.
Parameters 4
$userIdintThe account the device now belongs to.
$typestringThe account type: `member` or `admin`.
$windowintHow many days the trust lasts.
$uastringThe browser's raw User-Agent string. The trust token **is not passed**: handing it to a listener would spread it to a second place.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.device_trusted', 10, function ($userId, $type, $window, $ua) {
Acme::securityLog('device_trusted', $userId, ['type' => $type, 'days' => $window]);
});
```
#### Following device trust being revoked
actionuser.device_trust_revoked
`Auth` rows are already gone
Runs when an account's trusted devices are removed: a password reset, two-factor being switched on or off, a recovery-code sign-in, "sign out everywhere", or a removal from the account's own list.
Parameters 3
$userIdintThe account whose trust was revoked.
$typestringThe account type: `member` or `admin`. On a bulk clear with no type given it **arrives empty** — every type went.
$countintHow many devices were removed; a single removal always passes `1`.
Return 1
voidThe return is ignored; the rows are already deleted when it runs.
Listener PHP
```php
Hook::add('action:user.device_trust_revoked', 10, function ($userId, $type, $count) {
Acme::securityLog('trust_revoked', $userId, ['count' => $count]);
});
```
#### Stopping a password reset
gateuser.password_reset
`AdminUsers` the raw password
Runs before an administrator password is reset. Enforce your own password policy here.
Parameters 3
$user_idintThe account being reset.
$passwordstringThe new password **in the clear**. ? For a policy check only: do not log it, store it or send it anywhere.
$bystringWhere the reset came from.
Return 1
mixed**A filled return blocks it**: either a text or an array carrying a message. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:user.password_reset', 10, function ($user_id, $password, $by) {
// The raw password: check it only, write it NOWHERE.
if (strlen($password) < 16) return 'An administrator password needs at least 16 characters.';
return null;
});
```
#### Sending a customer to a screen of your own
gateuser.full_access
`website` returns a redirect
Runs when a customer enters the panel, **ahead of** the built-in access checks: missing fields, data consent and billing details all come after it.
Parameters 1
$idintThe customer signing in.
Return 1
string|null? It works the other way round from other gates: **returning a filled address** sends the customer there and **skips every built-in check**. Returning an address unconditionally switches off the missing-field and consent checks for good. Keep your condition narrow and return empty otherwise.
Listener PHP
```php
Hook::add('gate:user.full_access', 10, function ($id) {
// A filled return SKIPS THE BUILT-IN CHECKS: keep the condition narrow.
if (Acme::mustAcceptTerms($id)) return Utility::AppAdress() . '/acme/terms';
return null;
});
```
### Pitfalls
> **The access gate works the other way round**
>
> In other gates a filled return **blocks**; in the access gate a filled return **redirects and skips every built-in check**. Returning an address unconditionally switches off the missing-field and consent checks for good.
> **The password gate receives the raw password**
>
> The reset gate hands you the new password **in the clear**, which a policy check needs. Logging it, storing it or sending it anywhere leaks exactly what you set out to protect.
### Related Articles
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Sub-user Hooks
https://dev.wisecp.com/en/subuser-hooks
The seven hooks over inviting, accepting, updating and removing sub-users.
### Overview
Somebody else reaching an account starts with an invitation and ends with an acceptance. Every step between has its own hook: inviting, resending, accepting, updating, suspending and removing.
Three separate numbers must be kept apart: the **account**, the **person** reaching it and the sub-user **record**. Mixing them grants rights on the wrong account.
### Reference
#### Following a sub-user invitation
actionuser.subuser_invited
`AccountUsers` invitation waiting
Runs when a sub-user is invited to an account. **There is no access yet**: the invitation waits until it is accepted.
Parameters 4
$owner_idintThe account owner sending it.
$subuser_idintThe waiting invitation record created.
$emailstringThe invited address. That address **need not** already have an account.
$permsarrayThe permissions to be granted.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.subuser_invited', 10, function ($owner_id, $subuser_id, $email, $perms) {
// There is NO access yet: the invitation is waiting.
Acme::noteInvite($owner_id, $email);
});
```
#### Following an invitation being accepted
actionuser.subuser_accepted
`AccountUsers` access starts here
Runs when a sub-user accepts an invitation. **Access begins at this point**.
Parameters 3
$owner_idintThe account access was granted on.
$user_idintThe **real** user id of the sub-user; this is who signs in.
$subuser_idintThe id of the sub-user record. Three separate numbers: the account, the person and the record. Mixing them grants rights on the wrong account.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.subuser_accepted', 10, function ($owner_id, $user_id, $subuser_id) {
// Three separate numbers: the account, the person, the record.
Acme::grantAccess($owner_id, $user_id);
});
```
#### Following a sub-user being added
actionuser.subuser_added
`AccountUsers` added by an admin
Runs when a sub-user is added to an account.
Parameters 2
$user_idintThe account owner.
$subuserarrayThe record created: address, label and permissions.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.subuser_added', 10, function ($user_id, $subuser) {
Acme::syncTeam($user_id, $subuser);
});
```
#### Following a sub-user update
actionuser.subuser_updated
`AccountUsers` permissions included
Runs when the details or permissions of a sub-user change.
Parameters 2
$owner_idintThe account owner.
$subuserarrayThe updated data: address, label, status and permissions.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.subuser_updated', 10, function ($owner_id, $subuser) {
Acme::syncPermissions($owner_id, $subuser);
});
```
#### Following a sub-user status change
actionuser.subuser_status_changed
`AccountUsers` suspension
Runs when a sub-user is suspended or brought back.
Parameters 3
$owner_idintThe account owner.
$subuser_idintThe id of the record that changed.
$statusstringThe new state: `active` or `inactive`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.subuser_status_changed', 10,
function ($owner_id, $subuser_id, $status) {
if ($status === 'inactive') Acme::revokeTokens($subuser_id);
});
```
#### Following an invitation being sent again
actionuser.subuser_invite_resent
`AccountUsers` sent again
Runs when a waiting invitation is sent again.
Parameters 2
$owner_idintThe account owner sending it.
$subuser_idintThe record of the invitation resent.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.subuser_invite_resent', 10, function ($owner_id, $subuser_id) {
Acme::noteResend($owner_id, $subuser_id);
});
```
#### Following a sub-user being removed
actionuser.subuser_deleted
`AccountUsers` after deletion
Runs after a sub-user is removed from an account.
Parameters 2
$owner_idintThe account owner.
$subuserarrayThe full record before deletion: address, status and permissions.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.subuser_deleted', 10, function ($owner_id, $subuser) {
Acme::revokeAllAccess($owner_id, $subuser['email'] ?? '');
});
```
### Pitfalls
> **There are three separate numbers**
>
> The acceptance hook carries three ids: the **account** access was granted on, the **person** signing in and the sub-user **record**. Using the wrong one writes rights against another account.
> **An invitation is not access**
>
> When the invitation hook runs the other party can **reach nothing yet**. Access begins at the acceptance hook. A listener that opens rights on invitation turns an unaccepted invitation into real access.
### Related Articles
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Personal Data Hooks
https://dev.wisecp.com/en/personal-data-hooks
The nine hooks over consent, exports, data requests and identity documents.
### Overview
The four moments of personal data: a customer **gives consent**, **exports** their data, **asks for it to go**, and **submits identity documents**.
Two hooks deliberately withhold content: the document on export, the identity paper on submission. Listeners get only a summary, because spreading that data to a second place works against the point.
### Reference
#### Following a consent change
actionuser.gdpr_consent_changed
`AccountPrivacy` proof stamp
Runs when a customer gives or withdraws consent for data processing. It fires only on a **real change**: saving the same value again does not raise it.
Parameters 3
$uidintThe customer whose consent changed.
$statusintThe new state: one for given, zero for withdrawn. Since the hook fires only on a change, the previous state is always the opposite.
$given_atstringThe stamp written to the record. This is the time part of the consent proof: use this value rather than reading it back.
Return 1
voidThe return is ignored. The consent is already written; this cannot block it.
Listener PHP
```php
Hook::add('action:user.gdpr_consent_changed', 10, function ($uid, $status, $given_at) {
// Take the proof stamp from here rather than reading it back.
Acme::recordConsent($uid, (bool) $status, $given_at);
});
```
#### Following a data export
actionuser.gdpr_exported
`AccountPrivacy` summary only
Runs when a customer exports their own data.
Parameters 2
$uidintThe customer exporting.
$metaarrayA **summary** of the export: its format and size. The document content is withheld on purpose: passing it would hand every listener the customer’s personal data.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.gdpr_exported', 10, function ($uid, $meta) {
// The document content is deliberately withheld.
Acme::auditExport($uid, (int) ($meta['size'] ?? 0));
});
```
#### Following a data request being opened
actionuser.gdpr_request_created
`AccountPrivacy` two kinds
Runs when a customer opens a deletion or anonymisation request.
Parameters 2
$uidintThe customer opening it.
$typestringThe kind: `remove` for deletion, `anonymize` for anonymisation.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.gdpr_request_created', 10, function ($uid, $type) {
Acme::openComplianceCase($uid, $type);
});
```
#### Following a data request being cancelled
actionuser.gdpr_request_cancelled
`AccountPrivacy` withdrawn
Runs when a customer withdraws a request they opened.
Parameters 2
$uidintThe owner of the request.
$request_idintThe id of the cancelled request.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.gdpr_request_cancelled', 10, function ($uid, $request_id) {
Acme::closeComplianceCase($request_id);
});
```
#### Following a data request being carried out
actionuser.gdpr_processed
`AdminUsers` cannot be undone
Runs after a data request is carried out. **Deletion and anonymisation cannot be undone**: by this point the data is already gone.
Parameters 3
$request_idintThe request id.
$user_idintThe customer concerned.
$actionstringWhat was carried out: removal, anonymisation, destruction or cancellation.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.gdpr_processed', 10, function ($request_id, $user_id, $action) {
// The data is gone: clear your own copy as well.
if ($action !== 'cancelled') Acme::purgeMirror($user_id);
});
```
#### Following documents being submitted
actionuser.documents_submitted
`AccountDocuments` reference only
Runs when a customer submits identity documents.
Parameters 2
$uidintThe customer submitting. This flow is for the person themselves: a sub-user cannot submit on somebody else’s behalf.
$doc_metaarrayA summary of the submission. ? **No document content** is here, only references and metadata. It is deliberate, so identity documents are not handed to listeners.
Return 1
voidThe return is ignored. The records are already written; this cannot block the submission.
Listener PHP
```php
Hook::add('action:user.documents_submitted', 10, function ($uid, $doc_meta) {
// No document content, only the reference.
Acme::queueReview($uid);
});
```
#### Widening the document field types
filteruser.document_field_types
`AdminUsers` passed by link
Runs while the list of types offered when defining a document field is built. Add a field type of your own here.
Parameters 1
$typesarrayby linkType key against the visible label.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:user.document_field_types', 10, function (&$types) {
$types['acme-iban'] = 'Acme IBAN check';
});
```
#### Changing a document field definition
filteruser.document_field_input
`AdminUsers` passed by link
Runs before a document field is saved. Fill in the settings of a type you added here.
Parameters 2
$valuesarrayby linkThe row to be written: status, type, labels, options, accepted extensions and size limit.
$typestringby linkThe field type. It is there so you can tell whether this is your type: check it first.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:user.document_field_input', 10, function (&$values, &$type) {
// Check whether it is your type first.
if ($type !== 'acme-iban') return;
$values['max_size'] = 512;
});
```
#### Changing the document records view
filteruser.document_records_view
`AdminUsers` personal data
Runs when an administrator looks at a customer’s documents, before the records reach the screen.
Parameters 2
$recordsarrayby linkThe document records: field name, value, status. They carry identity details: this is where masking belongs.
$user_idintby linkThe customer being looked at; for reading only.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:user.document_records_view', 10, function (&$records, &$user_id) {
// Hide the identity number from eyes without clearance.
if (Acme::canSeeFullId()) return;
foreach ($records as $i => $r) $records[$i]['field_value'] = Acme::mask($r['field_value'] ?? '');
});
```
### Pitfalls
> **Content is withheld on purpose**
>
> The export hook does **not** carry the document, and the submission hook does not carry the identity paper; both give a summary only. That is design, not omission: handing the data to listeners works against the protection. If you need the content, read it through your own permitted path.
> **A processed request cannot be undone**
>
> By the time the removal or anonymisation hook runs the data is **already gone**. You must clear your own copy as well, or the customer's data lives on with you.
### Related Articles
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Account and Contact Hooks
https://dev.wisecp.com/en/account-contact-hooks
The eight hooks over the profile picture, addresses, linked providers and preferences.
### Overview
Everything a customer uses to describe themselves lives here: the profile picture, billing addresses, linked social accounts and notification preferences.
The address side carries four hooks: the save gate and its event, the default changing, and deletion. The default address is the one printed on invoices.
### Reference
#### Following a profile picture change
actionuser.avatar_changed
`AccountUsers` two branches
Runs when a customer uploads or removes a profile picture.
Parameters 3
$uidintThe account owner.
$actionstringWhat happened: `set` uploaded, `removed` taken away.
$picturestringThe path of the new picture. On the removal branch it is **always empty**: check the action before using the path.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.avatar_changed', 10, function ($uid, $action, $picture) {
// On the removal branch the path arrives EMPTY.
if ($action === 'removed') { Acme::dropAvatar($uid); return; }
Acme::mirrorAvatar($uid, $picture);
});
```
#### Stopping a contact being saved
gateuser.contact_save
`AccountUsers` zero means new
Runs before a customer saves a contact address.
Parameters 3
$uidintThe account the address will belong to.
$dataarrayThe address data: name, email, phone, country and tax details.
$idintThe id being edited; a **zero means a new one** is being added.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:user.contact_save', 10, function ($uid, $data, $id) {
// A zero id means a new record.
if (!Acme::taxNumberValid($data)) return 'The tax details did not verify.';
return null;
});
```
#### Following a contact being saved
actionuser.contact_saved
`AccountUsers` create and edit
Runs after a contact address is saved.
Parameters 4
$uidintThe owner of the address.
$saved_idintThe id of the saved address.
$dataarrayThe address data.
$is_newboolTrue when it was newly added.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.contact_saved', 10, function ($uid, $saved_id, $data, $is_new) {
Acme::syncContact($uid, $saved_id, $data);
});
```
#### Following the default contact changing
actionuser.contact_default_changed
`AccountUsers` default changed
Runs when an address becomes the default. The default is the address printed on invoices.
Parameters 2
$uidintThe owner of the address.
$idintThe address made default.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.contact_default_changed', 10, function ($uid, $id) {
// The default address is the one printed on invoices.
Acme::syncBillingAddress($uid, $id);
});
```
#### Following a contact being deleted
actionuser.contact_deleted
`AccountUsers` after deletion
Runs after a contact address is deleted.
Parameters 3
$uidintThe owner of the address.
$idintThe id deleted; the row is gone.
$existingarrayThe full address as read immediately before deletion.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.contact_deleted', 10, function ($uid, $id, $existing) {
Acme::dropContact($uid, $id);
});
```
#### Following a social account being linked
actionuser.connected_provider
`SocialAuth` account linking
Runs when an account is linked to an outside provider.
Parameters 2
$userobjectThe matched user record.
$mod_namestringThe name of the provider linked.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.connected_provider', 10, function ($user, $mod_name) {
Acme::noteLink((int) ($user->id ?? 0), $mod_name);
});
```
#### Following notification preferences changing
actionuser.notification_preferences_changed
`AccountUsers` per channel
Runs when a customer changes which notifications they receive.
Parameters 2
$uidintThe account whose preferences changed.
$prefsarrayWhat was written, **per channel**. The keys are deliberately the database column names, so which layer changed is never in doubt.
Return 1
voidThe return is ignored. The preferences are already written.
Listener PHP
```php
Hook::add('action:user.notification_preferences_changed', 10, function ($uid, $prefs) {
Acme::syncPreferences($uid, $prefs);
});
```
#### Producing the text of an activity record
filteruser.action_text
`User::addAction` only when empty
Runs while the visible text of an account activity is resolved. Produce the text for your own activity keys here.
Parameters 2
$textstringThe text the core found. The hook runs **only when no text was found**, so this is always empty. It is passed for signature consistency.
$ctxarrayContext: the activity key, the language asked for and the placeholder values.
Return 1
string|nullReturn the text you produced. Return nothing for keys that are not yours.
Listener PHP
```php
Hook::add('filter:user.action_text', 10, function ($text, $ctx) {
// The hook runs only when no text was found.
if (!str_starts_with($ctx['key'] ?? '', 'acme.')) return null;
return Acme::actionText($ctx['key'], $ctx['lang'] ?? '', $ctx['variables'] ?? []);
});
```
### Pitfalls
> **The picture path is empty on the removal branch**
>
> The profile picture hook fires for uploads and removals alike, and on removal the path field **always arrives empty**. A listener using the path directly then works with nothing on that branch.
> **The default address is the one on the invoice**
>
> Changing the default is more than a preference: the invoices that follow carry that address. If you keep an accounting side in step, listen on this hook too.
### Related Articles
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Account Restriction Hooks
https://dev.wisecp.com/en/account-restriction-hooks
The six hooks over blacklisting, bulk suspension, dormant accounts and bulk messages.
### Overview
The operations that narrow what an account may do live here: blacklisting, suspending or cancelling every service, and deleting an account left unused.
All of them reach wide and are hard to undo. That is what makes the gates valuable: they are the only place a wrong click can still be stopped.
### Reference
#### Stopping a blacklisting
gateuser.blacklist_add
`AdminUsers` before the write
Runs before a customer is put on the blacklist.
Parameters 3
$user_idintThe customer to be blacklisted.
$reasonstringThe reason code: payment fraud, chargeback, abuse, spam, terms breach, false information or other.
$restrictionsarrayThe restrictions to apply: new orders, renewals, tickets and suspending services.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:user.blacklist_add', 10, function ($user_id, $reason, $restrictions) {
// Ask for a second approval on an enterprise account.
if (Acme::isEnterprise($user_id)) return 'An enterprise account needs manager approval.';
return null;
});
```
#### Following a blacklist change
actionuser.blacklist_changed
`AdminUsers` three states
Runs after the blacklist state of a customer changes.
Parameters 4
$user_idintThe customer affected.
$statusstringWhat happened: `add`, `add-2` or `remove`. There are two separate adding values; a listener watching only one misses the other.
$reasonstringThe reason.
$admin_idintThe administrator who did it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.blacklist_changed', 10,
function ($user_id, $status, $reason, $admin_id) {
// There are two separate adding values.
if ($status !== 'remove') Acme::flagRisk($user_id, $reason);
});
```
#### Stopping a bulk service cancellation
gateuser.services_bulk_cancel
`AdminUsers` all at once
Runs before **every** service of a customer is cancelled. It is one click, and hard to undo.
Parameters 1
$user_idintThe customer whose services would be cancelled.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:user.services_bulk_cancel', 10, function ($user_id) {
// One click takes every service.
if (Acme::hasActiveContract($user_id)) return 'An account under contract cannot be cancelled in bulk.';
return null;
});
```
#### Following a bulk suspension
actionuser.services_bulk_suspended
`AdminUsers` all at once
Runs after every service of a customer is suspended.
Parameters 1
$user_idintThe customer whose services were suspended.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:user.services_bulk_suspended', 10, function ($user_id) {
Acme::notifyAccountFrozen($user_id);
});
```
#### Stopping a dormant account being deleted
gateuser.delete_dormant
`cronjobs` per account
Runs before an account left unused for a long time is deleted. The hook fires **per candidate**: one round can call it hundreds of times.
Parameters 2
$userIdintThe account up for deletion.
$uarrayThe candidate row: name, address and how long it has been dormant.
Return 1
string|null**A non-empty text skips this account** and the reason reaches the result report. Unlike other gates nothing is thrown: the round carries on with the remaining candidates.
Listener PHP
```php
Hook::add('gate:user.delete_dormant', 10, function ($userId, $u) {
// It runs per account: keep it light.
if (Acme::hasRetentionHold($userId)) return 'under a retention obligation';
return null;
});
```
#### Changing the bulk message recipients
filteruser.bulk_recipients
`AdminUsers` count and list together
Runs once the recipient pool for a bulk email or text message is built.
Parameters 4
$resultarrayby linkThe recipient pool: a count and the contacts. ? **Keep the two in step**: dropping a contact without adjusting the count shows a wrong recipient total on screen.
$dbTypestringWho it goes to: customers or staff.
$notifTypestringWhich channel: email or text message.
$filtersarrayThe filters applied.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:user.bulk_recipients', 10,
function (&$result, $dbType, $notifType, $filters) {
// The COUNT and the LIST must stay in step.
$result['contacts'] = Acme::dropOptedOut($result['contacts'] ?? []);
$result['count'] = count($result['contacts']);
});
```
### Pitfalls
> **Blacklisting has two separate adding values**
>
> The status field carries three values and **two of them mean adding**. A listener watching only one misses a customer blacklisted through the other path. Testing for removal and treating the rest as adding is safer.
> **Update the recipient list and the count together**
>
> The bulk recipient filter carries both the contacts and the count. Dropping a contact and leaving the count alone shows the administrator a **wrong recipient total** and skews the decision to send.
### Related Articles
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
# Hooks / Services
## Service Lifecycle Hooks
https://dev.wisecp.com/en/service-lifecycle-hooks
The 97 hooks opened across a sold service's life: setting up, suspending, cancelling, renewing, changing plan, and talking to the provider module.
### Overview
A service is the thing a customer bought: a hosting package, a server, a software licence. The hooks here follow its **life**. Most come in pairs: a gate in front of an action and an event behind it.
Another part is about the **module** actually providing the service. The code opening an account on a server, suspending it or changing a password lives there. These hooks let you touch that call's input and output.
### Reference
#### Life events
- **action:service.created**: A service was opened. The return value is ignored.
- **action:service.status_changed**: Its status changed. The return value is ignored.
- **action:service.suspended**: It was suspended. The return value is ignored.
- **action:service.terminated**: It was terminated. The return value is ignored.
- **action:service.cancelled**: It was cancelled. The return value is ignored.
- **action:service.deleted**: Its record was deleted. The return value is ignored.
- **action:service.renewed**: It was renewed. The return value is ignored.
- **action:service.updowngrade.applied**: A plan change was applied. The return value is ignored.
#### Gates
Eighteen gates. Two of them split one job in two. A module action called from the panel passes one gate, and the same action from the customer panel passes another. Where your rule holds for both, bind to **both**.
- **gate:service.suspend**: Suspending.
- **gate:service.cancel**: Cancelling.
- **gate:service.delete**: Deleting.
- **gate:service.upgrade**: Upgrading the plan.
- **gate:service.manual_renew**: Renewing by hand.
- **gate:service.status_change**: Changing the status.
- **gate:service.module_action**: A module action from the panel.
- **gate:service.client_tool**: A module action from the customer panel.
- **gate:service.transfer_request**: A transfer request.
- **gate:service.autorenew_toggle**: Switching auto-renewal on and off.
#### The provider module
- **action:service.module_ran**: An action ran on the provider module.
- **filter:service.module_result**: What the module returned.
- **filter:service.build_options**: The options going to the module while a service is built. The array changes by reference and the changed array is what gets written; the return value is not used.
- **filter:service.config_fields**: The service's configuration fields.
- **filter:service.module_username**: The username used on the module.
- **action:service.password_changed**: The service password changed.
#### The detail screen's data
- **filter:service.detail_data**: The data behind a service detail.
- **filter:service.dashboard.cards**: The cards on a service dashboard.
- **filter:service.dashboard.tools**: The tools on a service dashboard.
- **filter:service.detail_tabs_capabilities**: Which capabilities the detail tabs show.
- **filter:service.upgrade_products**: The products offered for an upgrade.
#### A gate and an event together
```php
// A GATE: do not suspend a service under review (ask us first).
Hook::add('gate:service.suspend', 10, function ($service) {
if (Acme::onHold((int) ($service['id'] ?? 0)))
return 'This service is under review; the suspend was stopped.';
return null;
});
// AN EVENT: tell the outside once it was suspended.
Hook::add('action:service.suspended', 10, function ($id, $service) {
Crm::suspended((int) $id);
});
```
### Pitfalls
> **Automatic actions pass these hooks too**
>
> Suspending, terminating and renewing also run from **scheduled tasks**. A gate saying "the operator should not do this" also lands on the job running overnight, and the system cannot do its own work. Write a gate thinking about who it stops.
> **The event does not prove the work landed on the server**
>
> The status hook runs when **our record** changes. Whether the provider module truly closed the account on the server is a separate question, and the record can change even where the module call failed. Where the server side matters, read the filter carrying the module result.
> **The panel and customer paths are separate gates**
>
> Module actions pass two separate gates: one for the operator in the panel, one for the customer in theirs. Binding to only one means your rule **can be walked around** by the other path. The customer path is also narrower: only the methods a module openly allows can be called.
> **A renewal can show up twice**
>
> A renewal can come from an invoice being paid or from a manual action, and a subscription collection takes the same path. Writing work that follows a renewal, be ready to run **twice for one period** and weed out the repeat on your side.
### Related Articles
- Order Flow Hooks
- Invoice and Payment Hooks
- Module Lifecycle Hooks
## Service Status Hooks
https://dev.wisecp.com/en/service-status-hooks
Nine hooks from a sold service opening to its record going: setting up, status changes, suspending, terminating and deleting.
### Overview
A service lives in **two places at once**: as a row in our database and as a real account at the end of a provider module. Most hooks here speak about the first.
Knowing that split matters: when a status changes, **our record** changed. Whether the account on the server truly closed is a separate question, and usually the outcome of a job that was **queued**.
### Reference
#### Changing the service about to be created
filterservice.save_data
`Hook::runRefs` by reference
Runs before the service row is written to the database.
Parameters 1
$dataarrayrefThe row about to be written: `user_id`, `product_id`, `options`, `status`, `duedate`. What you change here goes straight to the database.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.save_data', 10, function (&$data) {
// Put your own tracking key inside options; do not add a column.
$data['options']['acme_batch'] = Acme::currentBatch();
});
```
#### Learning that a service opened
actionservice.created
`Services::create()` the row landed
Runs after the service row was written. The account at the provider may **not exist yet** at this point.
Parameters 2
$idintThe new service id.
$dataarrayThe data that was written. It has passed the filter, so your changes show here.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.created', 10, function ($id, $data) {
// The row exists, the account may not: do not wait on provisioning here.
Crm::opened((int) $id, (int) ($data['user_id'] ?? 0));
});
```
#### Stopping a status change
gateservice.status_change
`Services::change_status()` both states
Runs before the service status changes, handing you both the old state and the target.
Parameters 3
$servicearrayThe service record with its **current** status.
$statusstringThe target: `active`, `suspended`, `cancelled`, `inprocess`.
$oldStatusstringThe current status. Read both together to target one particular transition.
Return 1
stringA non-empty string **stops** the transition; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:service.status_change', 10,
function ($service, $status, $oldStatus) {
// Check only the reopening of a cancelled service.
if ($oldStatus === 'cancelled' && $status === 'active'
&& !Acme::reactivationAllowed($service))
return 'A cancelled service reopens with an operator\'s approval.';
return null;
});
```
#### Following a status change
actionservice.status_changed
`Services::change_status()` the module may have overridden
Runs after the status changed. The value you get is the **final** one, after any override by the module.
Parameters 4
$serviceIdintThe service id.
$statusstringThe new status. It can **differ** from the one asked for where the module stepped in.
$oldStatusstringThe previous status.
$servicearrayA snapshot of the service **before** the change.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.status_changed', 10,
function ($serviceId, $status, $oldStatus, $service) {
// Do no work again where it landed back on the same status.
if ($status === $oldStatus) return;
Crm::statusMoved($serviceId, $oldStatus, $status);
});
```
#### Stopping a suspend
gateservice.suspend
`cronjobs/ServiceSuspend` a veto turns into a cancel
Runs before a service or add-on is suspended. **Stopping it has a cost**: the job turns into a cancel signal.
Parameters 4
$target_typestring`service` or `addon`. One hook carries both.
$target_idintThe id of the record being suspended.
$servicearrayThe live row: `status`, `duedate`, `module`, `owner_id`.
$user_idintThe service owner.
Return 1
stringA non-empty string **vetoes** the suspend — and it does not end there: the signal turns into a **cancel** and your reason is recorded. So "do not suspend" is not the same as "do nothing".
Listener PHP
```php
Hook::add('gate:service.suspend', 10,
function ($target_type, $target_id, $service, $user_id) {
if ($target_type !== 'service') return null; // leave add-ons alone
// MIND: a veto stops the suspend but turns the job into a CANCEL signal.
if (Acme::vipAccount($user_id)) return 'VIP account: review by hand.';
return null;
});
```
#### Following a suspend
actionservice.suspended
`cronjobs/ServiceSuspend` the module job is queued
Runs after the service was suspended. The actual closing on the server was **queued**.
Parameters 5
$target_typestring`service` or `addon`.
$target_idintThe id of the suspended record.
$user_idintThe service owner.
$reasonstringThe reason, **translated into the customer's language**.
$module_queue_idintThe queue id of the module job. `0` means it was **never queued**: on a service without a module nothing happens on the server side.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.suspended', 10,
function ($target_type, $target_id, $user_id, $reason, $module_queue_id) {
// A queue id of 0 means nothing was done on the server.
if ($module_queue_id === 0) Ops::note('suspend-no-module', $target_id);
});
```
#### Following a termination
actionservice.terminated
`cronjobs/ServiceTerminate` the server side
Runs after the service was terminated. This hook carries the **server side**: which module, which server.
Parameters 5
$target_idintThe id of the terminated service.
$service_typestring`hosting` or `server`.
$modulestringThe server module's name.
$server_idintThe server the service sat on.
$module_queue_idintThe queue id of the termination job.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.terminated', 10,
function ($target_id, $service_type, $module, $server_id, $module_queue_id) {
// Capacity came free on that server: update your own counter.
Capacity::released((int) $server_id, $service_type);
});
```
#### Stopping a service delete
gateservice.delete
`Services::delete()` the record goes
Runs before the service record is deleted. Deleting is **not the same** as closing the account on the server: it removes our record alone.
Parameters 1
$servicearrayThe service record about to be deleted.
Return 1
stringA non-empty string **stops** the delete; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:service.delete', 10, function ($service) {
// Deleting a live service leaves an orphaned account on the server.
if (($service['status'] ?? '') === 'active')
return 'A live service cannot be deleted; terminate it first.';
return null;
});
```
#### Following a delete
actionservice.deleted
`Services::delete()` a last snapshot
Runs after the service record was deleted.
Parameters 2
$idintThe id of the deleted service.
$servicearrayA snapshot from **before** the delete. Take what you need from here; the record is gone.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.deleted', 10, function ($id, $service) {
Acme::forgetService((int) $id, $service['name'] ?? '');
});
```
### Pitfalls
> **A suspend veto becomes a cancel**
>
> Returning a non-empty text at the suspend gate does not stop the work, it **turns it into a cancel**. A rule written as "do not suspend this one" can end with the service **cancelled outright**. Write here knowing what follows.
> **A queue id of zero means nothing happened on the server**
>
> The suspend and terminate hooks hand you a **queue id**. Zero means the module job was **never created**: the service has no module, or the server is unknown. Our record changed and nothing happened on the server.
> **The final status may not be the one asked for**
>
> The status event hands you the value **after any override by the module**. The target you saw at the gate and the value in the event can **differ**. Reacting to a transition, read the value from the event rather than the intent at the gate.
> **Deleting is not closing**
>
> Deleting a service removes **our record** and nothing else. The account on the server stays where it is, now visible from nowhere. Where the server side should close too, terminate first and delete after.
### Related Articles
- [Service Lifecycle Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- Order Flow Hooks
- Scheduled Task Hooks
## Service Module Hooks
https://dev.wisecp.com/en/service-module-hooks
The eight hooks talking to the module that truly provides a service: the gates before a call, the parameters going out and the result coming back.
### Overview
The code opening an account on a server, suspending it or changing a password lives **in the module**. The core says "do this" and waits for the outcome.
This path has **two separate gates** and mixing them up is common: one for calls from the panel, one for calls from the customer's own panel. The customer path is narrower and cannot reach past the methods a module openly allows.
### Reference
#### Changing the options a service is built with
filterservice.build_options
`Orders::buildServices()` from order to service
Runs while a service is built from an order item, before the record is written.
Parameters 3
$service_dataarrayrefThe whole payload of the service to be built: `type`, `product_id`, `amount`, `status`, `module`, `options`, `metrics`.
$itemarrayThe source order item. Read-only context; what the customer picked at order time is here.
$productarrayThe resolved product row. Read-only context.
Return 1
voidThe values change **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.build_options', 10,
function (&$service_data, $item, $product) {
// Fill in module options from what the order says.
$service_data['options']['acme_region'] = Acme::region($item);
});
```
#### Changing what the module is built with
filterservice.module_context
`Hook::runRefs` before the module object exists
Runs in `Services::run_module()`, immediately before the module object is built. The module reads `$service['options']` at construction time, so this is the last point where a change still reaches the provider — the gate below already runs too late for that.
Parameters 3
$servicearrayrefThe service record. Its `options` is what the module object is built from.
$actionstringrefThe action about to run. Alias resolution (`terminate` → `cancel`) happens after this hook, so a new value is resolved too.
$paramsarrayrefThe arguments the module method will receive.
Return 1
voidThe values change **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.module_context', 10,
function (&$service, &$action, &$params) {
if ($action !== 'create') return;
// Written into the copy the module is about to be built from; persist it
// separately if it also has to survive in the record.
$options = is_array($service['options'] ?? null) ? $service['options'] : [];
$options['ip'] = Acme::reserve((int) $service['id']);
$service['options'] = $options;
});
```
> **Every create path passes here, and only here**
>
> The up/downgrade rebuild hands `run_module()` a **prepared array** and never re-reads the row. A listener that only follows `action:service.created` misses that path, and the service is provisioned without whatever the listener meant to add.
#### Stopping a module action
gateservice.module_action
`Services::run_module()` the panel path
Runs before the module method is called. This gate stands on calls from **the panel**.
Parameters 3
$servicearrayThe service record.
$actionstringThe action about to run: `create`, `suspend`, `cancel` and the like.
$paramsarrayThe parameters going to the module method.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the module is never called.
Listener PHP
```php
Hook::add('gate:service.module_action', 10, function ($service, $action, $params) {
// Send no write action to a server inside its maintenance window.
if (in_array($action, ['create', 'suspend', 'cancel'], true)
&& Acme::maintenance((int) ($service['server_id'] ?? 0)))
return 'The server is under maintenance; this cannot run now.';
return null;
});
```
#### Following a module call
actionservice.module_ran
`Services::run_module()` one array parameter
Runs after the module method ran — **whether it worked or not**.
Parameters 1
$payloadarrayIt carries a single array: `service`, `instance` (the module object), `action`, `result`, `error`. Unlike the other hooks the parameters do **not arrive separately**; they all sit inside this one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.module_ran', 10, function ($payload) {
// ONE parameter arrives; the error field inside it reports the failure.
if (!empty($payload['error']))
Ops::alert('module-failed', $payload['action'] ?? '', $payload['error']);
});
```
#### Changing the module result
filterservice.module_result
`Hook::runRefs` all five by reference
Runs before the module's return is handled by the core. **All five arguments** arrive by reference.
Parameters 5
$servicearrayrefThe service record.
$instanceobjectrefThe module object.
$actionstringrefThe action that ran.
$resultmixedrefWhat the module returned: a config array, login details, `false`, or something else. This is the one you usually change.
$errormixedrefThe error message or `null`. Writing here tells the core "this failed".
Return 1
voidThe values change **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.module_result', 10,
// Defaults are REQUIRED: $error is null when the module succeeds, and a null argument is
// dropped, so a listener with five required parameters never runs on a successful call.
function (&$service = null, &$instance = null, &$action = null, &$result = null, &$error = null) {
// Turn a provider's temporary error into something worth retrying.
if ($error && Acme::transient((string) $error)) {
$error = null;
$result = false; // the core reads a failure, raises no alarm
}
});
```
#### Stopping a call from the customer panel
gateservice.client_tool
`ClientServices` the customer path
Runs where a customer calls a module action from their own panel. This gate is **separate** from the panel one.
Parameters 3
$servicearrayThe customer's own service.
$methodNamestringThe real module method about to run: a directly callable name (`sso_panel_login`) or the `handle_` form.
$moduleobjectThe module object. Built in customer mode, with panel-only rows already dropped.
Return 1
stringA non-empty string **stops** the call; it reaches the customer as the error.
Listener PHP
```php
Hook::add('gate:service.client_tool', 10, function ($service, $methodName, $module) {
// One-click panel entry is sensitive: close it to unverified accounts.
if ($methodName === 'sso_panel_login' && !Acme::verified($service))
return 'Verify your account before entering the panel.';
return null;
});
```
#### Following a customer call
actionservice.client_tool_ran
`ClientServices` two method names
Runs after the module method the customer called has run.
Parameters 4
$servicearrayThe service record.
$methodstringThe name **at request level**: `tool_action`, `tool_table`, `sso_panel_login`, or a key the module opened.
$methodNamestringThe module method that **actually ran**. The two often differ, so mind which one you read.
$moduleResultmixedWhat the module returned. Output the module printed directly is **not** in here.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.client_tool_ran', 10,
function ($service, $method, $methodName, $moduleResult) {
// The request name and the real method differ: record BOTH.
Audit::clientTool((int) ($service['id'] ?? 0), $method, $methodName);
});
```
#### Changing the configuration fields
filterservice.config_fields
`Hook::runRefs` fields and actions
Runs after the configuration screen the module offers was built.
Parameters 2
$configarrayrefIt carries two keys: `actions` and `fields`. You can add fields, drop them or make them read-only.
$moduleServerModuleThe service's module object.
Return 1
voidThe values change **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.config_fields', 10, function (&$config, $module) {
// Show a dangerous action to nobody but an operator.
unset($config['actions']['rebuild']);
});
```
#### Following a service password change
actionservice.password_changed
`ClientServices` the password is not carried
Runs after the service's panel password changed.
Parameters 2
$servicearrayThe service whose password changed.
$uidintThe account id of the service owner.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.password_changed', 10, function ($service, $uid) {
// The new password NEVER reaches the hook; report only that it changed.
Notify::securityEvent($uid, 'service-password', (int) ($service['id'] ?? 0));
});
```
#### Following a server change
actionservice.server_changed
`AdminServices` after the move
Runs after a service is assigned to a different server. The record moved, but **nobody moved the data**: this hook is where you start that.
Parameters 4
$idintThe id of the service.
$currentServerIdintThe previous server; a **zero** means it had none.
$new_server_idintThe new server; a **zero** means it was taken off one.
$newServerTypestringThe module type now set on the service.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.server_changed', 10,
function ($id, $currentServerId, $new_server_id, $newServerType) {
// The record moved, the data did not: start the migration yourself.
if ($currentServerId && $new_server_id)
Acme::queueMigration($id, $currentServerId, $new_server_id);
});
```
### Pitfalls
> **There are two gates and neither covers the other**
>
> Calls from the panel pass one gate and calls from the customer panel pass **another**. A rule bound to only one **can be walked around** by the other path. Where your rule holds for both sides, bind to both.
> **The module event carries one array**
>
> Where other hooks hand you separate parameters, the module-ran hook hands you **one array**. A listener expecting four parameters fails not because the hook throws two, but because it throws **one**. Reading the error field inside it is also the only way to tell success from failure.
> **The result filter can write the error too**
>
> On the result filter **all five arguments** are by reference: you can change the result *and* the error. Clearing the error tells the core "this did not fail"; used carelessly it **hides a real failure** and nobody notices.
> **The customer path is narrow already**
>
> From the customer panel only the methods a module **openly allows** can be called; creating, terminating and suspending never reach there. Check that before adding a rule at the gate: what you mean to block may be closed **already**.
### Related Articles
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- Module Lifecycle Hooks
- [Service Lifecycle Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
## Service Cancellation Hooks
https://dev.wisecp.com/en/service-cancellation-hooks
The seven hooks running where a customer says "I no longer want this": the request, the approval, taking it back, and the cancellation itself.
### Overview
Cancelling has **two layers**, and mixing them up puts your code in the wrong place. The upper layer is **the request**: a customer asks, an operator approves, or the customer takes it back. The lower layer is **the work**: the service is truly closed.
The request layer keeps a record and talks to the customer. The work layer runs from a scheduled task and reaches the provider. A service can also be cancelled **with no request at all**: an unpaid invoice does that on its own.
### Reference
#### Stopping a cancellation request
gateservice.cancellation_request
`ClientServices` the customer asks
Runs before the customer's cancellation request is created. Stopping it means **no request is recorded**.
Parameters 3
$servicearrayThe customer's own service. Domains do not pass this flow.
$urgencystringThe timing: `now`, or `period-ending` at the end of the term. Two very different things: one closes the service today, the other waits out a paid term.
$reasonKeystringThe reason key: `not-needed`, `too-expensive`, `switching`, `missing-features`, `other`.
Return 1
stringA non-empty string **stops** the request; it reaches the customer as the error.
Listener PHP
```php
Hook::add('gate:service.cancellation_request', 10,
function ($service, $urgency, $reasonKey) {
// A service under contract does not close before its term ends.
if ($urgency === 'now' && Acme::underContract($service))
return 'No immediate cancellation while the contract runs.';
return null;
});
```
#### Following a cancellation request
actionservice.cancellation_requested
`ClientServices` it hands you a record id
Runs after the request was recorded. The service is **still running** at this point.
Parameters 5
$servicearrayThe service record.
$urgencystringThe timing: `now`, or `period-ending` at the end of the term. Two very different things: one closes the service today, the other waits out a paid term.
$reasonKeystringThe reason key: `not-needed`, `too-expensive`, `switching`, `missing-features`, `other`.
$reasonstringThe stored reason text: the label in the customer's language plus any free note. On `other` only the free text arrives.
$eventIdintThe id of the created request record. The approve and revoke hooks come back to the same one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.cancellation_requested', 10,
function ($service, $urgency, $reasonKey, $reason, $eventId) {
// The service is STILL running: this is an intent, not a closing.
Retention::opened($eventId, $reasonKey, $urgency);
});
```
#### Stopping a cancellation approval
gateservice.cancellation_accept
`AdminServices` the operator approves
Runs before the operator approves a cancellation request.
Parameters 2
$service_idintThe id of the service to be cancelled. An **id** arrives, not the service record.
$requestarrayThe request record: `id`, `owner_id` and the decoded `data` (timing, reason).
Return 1
stringA non-empty string **stops** the approval; it reaches the operator as the error.
Listener PHP
```php
Hook::add('gate:service.cancellation_accept', 10, function ($service_id, $request) {
// Cancelling with an unpaid invoice open loses the money owed.
if (Acme::hasUnpaid($service_id)) return 'Settle the unpaid invoice first.';
return null;
});
```
#### Following a cancellation approval
actionservice.cancellation.accepted
`AdminServices` approved
Runs after the operator approved the request.
Parameters 3
$serviceIdintThe service id.
$cancellationTypestringThe kind: now, or at the end of the term. Where the term end was chosen the service **does not close today**.
$requestDataarrayThe request data: the reason and who approved it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.cancellation.accepted', 10,
function ($serviceId, $cancellationType, $requestData) {
// On a term-end cancellation nothing closes today; hold your counter.
if ($cancellationType === 'now') Capacity::freed($serviceId);
});
```
#### Following a request taken back
actionservice.cancellation_revoked
`ClientServices` the customer changed their mind
Runs where the customer took their cancellation request back.
Parameters 3
$servicearrayThe service record.
$eventarrayThe request record **as it was before** deletion, holding the timing, the reason key, the reason text and any note. The record is gone, so read it here.
$uidintThe account id of the service owner.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.cancellation_revoked', 10,
function ($service, $event, $uid) {
// Taking it back is a retention win: close the record.
Retention::closed((int) ($event['id'] ?? 0), 'revoked');
});
```
#### Stopping the cancellation work
gateservice.cancel
`cronjobs/ServiceCancel` a veto still cancels
Runs before a service or add-on is truly cancelled. This gate sits **below** the request layer.
Parameters 4
$target_typestring`service` or `addon`.
$target_idintThe id of what is being cancelled.
$servicearrayThe live row: `status`, `type`, `module`, `duedate`.
$user_idintThe service owner.
Return 1
stringA non-empty string **vetoes** the cancel — and the job still turns into a **cancel signal**, with your reason recorded. Same behaviour as the suspend gate: a veto is not "nothing happens".
Listener PHP
```php
Hook::add('gate:service.cancel', 10,
function ($target_type, $target_id, $service, $user_id) {
// With data still moving you may want the cancel held.
if (Acme::migrationRunning($target_id)) return 'A migration is running.';
return null;
});
```
#### Following an add-on cancellation request
actionservice.addon.cancellation_requested
`ClientServices` at period end
Runs when a customer asks for an add-on to end at the close of its period. The request is recorded but **the add-on is still live** and keeps working until the due date.
Parameters 5
$servicearrayThe service the add-on belongs to.
$addonarrayThe add-on being cancelled. At this moment the row is still active; the cancellation lands on the due date.
$reasonstringWhat the customer wrote. The field is optional, so it **can arrive empty**. It is cut at 300 characters.
$eventIdintThe id of the cancellation request record.
$uidintThe account that owns the add-on. A sub-user may have done the clicking; that is a different id.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.addon.cancellation_requested', 10,
function ($service, $addon, $reason, $eventId, $uid) {
// Start the win-back offer: the add-on still runs, there is time.
Acme::offerRetention($uid, $addon['addon_name'] ?? '', $reason);
});
```
#### Following a cancellation being taken back
actionservice.addon.cancellation_revoked
`ClientServices` changed their mind
Runs when a customer takes back a cancellation request. This is where you stop the win-back flow you started.
Parameters 4
$servicearrayThe service the add-on belongs to.
$addonarrayThe add-on whose cancellation was taken back.
$eventarrayThe **deleted** request record, reason and approval included. By the time the hook runs that row is gone from the database; this is the last copy of it.
$uidintThe account that owns the service.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.addon.cancellation_revoked', 10,
function ($service, $addon, $event, $uid) {
Acme::stopRetention($uid, $addon['addon_name'] ?? '');
});
```
#### Following a scheduled downgrade being cancelled
actionservice.scheduled_downgrade_cancelled
`ClientServices` changed their mind
Runs when a downgrade set for the due date is called off. The service carries on with the package it has.
Parameters 3
$servicearrayThe service record. The package **did not change**: the downgrade was planned, never applied.
$scheduledarrayThe cancelled plan, **as it was before the update**. Its status field still holds the old value.
$uidintThe account that owns the service.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.scheduled_downgrade_cancelled', 10,
function ($service, $scheduled, $uid) {
// Take the downgrade back out of your capacity forecast.
Acme::releaseForecast((int) ($service['id'] ?? 0));
});
```
### Pitfalls
> **A request and a cancellation are not the same**
>
> The request hooks run where a customer **asks**; the service is still up. The real closing happens on the cancel hooks below. Freeing capacity, deleting data or raising a final invoice from the request hook leaves damage you cannot undo **where the customer takes it back**.
> **A term-end cancellation closes nothing today**
>
> The kind on the approval hook is either **now** or **the end of the term**. On the second the service runs to the end of the paid period. A listener assuming "cancelled" without reading it counts a service the customer is still using as closed.
> **A cancel veto does not prevent the cancel**
>
> Returning text at the cancel gate does not stop the work; the signal **still turns into a cancel** and only your reason is recorded. The same trap as the suspend gate. To truly prevent it, act on **the request layer**.
> **Not every cancellation comes from a request**
>
> An unpaid invoice takes a service to cancellation **with no request**. A system listening only to the request hooks never sees those. To see every cancellation, listen to the status hook on the layer below.
### Related Articles
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- Invoice and Payment Hooks
- [Service Lifecycle Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
## Service Renewal Hooks
https://dev.wisecp.com/en/service-renewal-hooks
The eight hooks extending a service and changing its plan: renewals, auto-renewal, upgrades and downgrades.
### Overview
A renewal arrives by **three separate paths**: the customer starts one by hand, auto-renewal charges a stored card, or a paid invoice triggers it. All three meet at the same event hook.
A plan change is not one step. The request is taken, a **flow** is picked by the payment situation (an invoice was raised, it was scheduled for the term end, or it went straight to the queue), and the change lands only at the end.
### Reference
#### Stopping a manual renewal
gateservice.manual_renew
`ClientServices` the manual path only
Runs where a customer starts a renewal by hand, before the renewal engine is **called at all**.
Parameters 2
$servicearrayThe service being renewed.
$renew_optsarrayThe options going to the engine: `source` (here `manual`), plus the add-on discovery, metric and notification flags. This gate sees the manual path alone; auto-renewal and the invoice path do not pass here.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and shown to the customer.
Listener PHP
```php
Hook::add('gate:service.manual_renew', 10, function ($service, $renew_opts) {
// Renewing a suspended service spends money for nothing; open it first.
if (($service['status'] ?? '') === 'suspended')
return 'A suspended service wants activating first.';
return null;
});
```
#### Learning that a renewal landed
actionservice.renewed
`Services::process_renewal()` the record holds the OLD date
Runs after the date was extended. **All three renewal paths** arrive here.
Parameters 4
$serviceIdintThe id of the renewed service.
$servicearrayA snapshot from **before** the extension. The date, term and amount are still the **old** ones; do not read the new date from here.
$newDuedatestringThe new date that was written. It never moves backwards: the **later** of the candidate and the current one is kept.
$oldDuedatestringThe date before the extension. The same as the one on the record, passed separately for an easy comparison.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.renewed', 10,
function ($serviceId, $service, $newDuedate, $oldDuedate) {
// Did the date REALLY move? The same one can be written again.
if ($newDuedate === $oldDuedate) return;
Crm::renewed($serviceId, $oldDuedate, $newDuedate);
});
```
#### Stopping the auto-renewal switch
gateservice.autorenew_toggle
`ClientServices` the state being asked for
Runs while a customer switches auto-renewal on or off, with the value **not written yet**.
Parameters 3
$servicearrayThe service record. Its auto-renewal field still holds the **old** value.
$enableboolThe **new** state being asked for.
$uidintThe service **owner**. A sub-user may be the one acting; that id does not arrive here.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and shown to the customer.
Listener PHP
```php
Hook::add('gate:service.autorenew_toggle', 10, function ($service, $enable, $uid) {
// Switching it off lets the service lapse quietly: hold it while money is owed.
if (!$enable && Acme::hasDebt($uid))
return 'Auto-renewal stays on while a balance is owed.';
return null;
});
```
#### Following the auto-renewal switch
actionservice.autorenew_changed
`ClientServices` the record holds the OLD value
Runs after the value was written.
Parameters 2
$servicearrayThe service record, read **before** the change. Its auto-renewal field still holds the old value; the new state is the second parameter.
$enableboolThe **new** state that was written.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.autorenew_changed', 10, function ($service, $enable) {
// The new state is the SECOND parameter; the field on the record is old.
if (!$enable) Retention::flag((int) ($service['id'] ?? 0), 'autorenew-off');
});
```
#### Stopping a plan change
gateservice.upgrade
`Services` up and down
Runs before a plan change starts. **Both** upgrades and downgrades pass here.
Parameters 5
$servicearrayThe current service row.
$old_pidintThe id of the current product.
$product_idintThe id of the target product.
$price_dataarrayThe resolved target price row.
$isUpbool`true` for an upgrade, `false` for a downgrade. Read the direction here rather than working it out from the product ids.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and shown to the customer.
Listener PHP
```php
Hook::add('gate:service.upgrade', 10,
function ($service, $old_pid, $product_id, $price_data, $isUp) {
// A downgrade can lose data: stop an account already over the target.
if (!$isUp && Acme::usageAbovePlan($service, $product_id))
return 'Your current usage does not fit the target plan.';
return null;
});
```
#### Following a plan change request
actionservice.plan_change_requested
`ClientServices` three separate flows
Runs after the request was taken. The flow value says **when the change lands**.
Parameters 6
$servicearrayThe service record, still on the **old** plan.
$old_pidintThe id of the old product.
$new_pidintThe id of the wanted product.
$flowstringThe resulting flow: `invoice_unpaid` (an invoice was raised and is **unpaid**), `scheduled` (set for the term end), `queued` (free of charge, straight to the queue). On all three the change has **not landed yet**.
$updown_idintThe id of the created plan-change record.
$invoice_idintThe id of the raised invoice, or `0` where there is none.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.plan_change_requested', 10,
function ($service, $old_pid, $new_pid, $flow, $updown_id, $invoice_id) {
// The change has NOT landed; the flow says when it will.
if ($flow === 'invoice_unpaid') Crm::awaitPayment($invoice_id, $updown_id);
});
```
#### Learning that a plan change landed
actionservice.updowngrade.applied
`Services` one array parameter
Runs after the plan change was truly applied.
Parameters 1
$payloadarrayA single array: `service_id`, `old_service`, `new_product`, `type` (`upgrade` or `downgrade`), `needs_recreate`, `params`. A true `needs_recreate` means the service will be **rebuilt** on the server.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.updowngrade.applied', 10, function ($payload) {
// A rebuild means downtime for a while: tell the customer.
if (!empty($payload['needs_recreate']))
Notify::planRebuild((int) ($payload['service_id'] ?? 0));
});
```
#### Changing the plans on offer
filterservice.upgrade_products
`Hook::runRefs` by reference
Runs after the upgrade options shown to the customer were built.
Parameters 1
$productsarrayrefThe products on offer. Dropping one hides it on the screen; using this rather than the gate keeps the customer from seeing **an option they cannot take**.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.upgrade_products', 10, function (&$products) {
// Never show a plan you would refuse at the gate.
$products = array_values(array_filter($products,
fn ($p) => Acme::sellable((int) ($p['id'] ?? 0))));
});
```
#### Following an add-on renewal
actionservice.addon.renewed
`handle_extend_addon_paid` after payment
Runs after an add-on gets a longer term. Payment has landed and the new due date is written.
Parameters 5
$addonIdintThe id of the add-on record.
$addonarrayThe add-on row **as it was before the extension**. Its due date and amount hold the old values; take the new ones from the separate parameters.
$servicearrayThe parent service record.
$newDuedatestringThe new due date that was written.
$oldDuedatestringThe due date before the extension.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.addon.renewed', 10,
function ($addonId, $addon, $service, $newDuedate, $oldDuedate) {
// Move the entitlement on the outside licence to the new due date.
Acme::extendEntitlement($addonId, $newDuedate);
});
```
#### Following the repeat count running out
actionservice.recurring_completed
`generate_renewal` final cycle
Runs when a product reaches its set number of repeats and the **last** renewal invoice is made. Nothing renews automatically after this.
Parameters 4
$service_idintThe id of the service that ran out.
$servicearrayThe service record.
$countintHow many renewals were made for this service.
$limitintThe repeat limit set on the product.
Return 1
voidThe return is ignored. The invoice already exists and cannot be stopped here.
Listener PHP
```php
Hook::add('action:service.recurring_completed', 10,
function ($service_id, $service, $count, $limit) {
// Catch the final cycle: send the customer an offer to carry on.
Acme::offerContinuation((int) ($service['owner_id'] ?? 0), $service_id);
});
```
#### Changing the auto-payment answer
filterservice.auto_pay_source_available
`ClientAutoRenewGuard` passed by link
Runs before the question "can the renewal job charge this account without the customer present?" is answered. Declare a source the core does not know about here.
Parameters 2
$availableboolby linkWhat the core decided. You may write over it.
$ctxarrayContext: `owner_id`, the account being asked about.
Return 1
voidThe return is ignored; you change the value in place. Saying yes grants permission to **try**. If your source cannot actually charge, the renewal fails and the service is suspended.
Listener PHP
```php
Hook::add('filter:service.auto_pay_source_available', 10,
function (&$available, $ctx) {
if ($available) return; // the core already found a source
// Declare the mandate you keep yourself.
$available = Acme::hasMandate((int) ($ctx['owner_id'] ?? 0));
});
```
### Pitfalls
> **On the renewal event the record holds the OLD date**
>
> The service in the second parameter is a snapshot from **before** the extension: its date, term and amount are the old ones. The new date is **the third parameter**. Reading the record and concluding "not renewed" comes from here. The date also never moves backwards, so old and new can be **the same**.
> **A plan change request is not the change**
>
> On the request hook the change has **not landed**. The flow can say one of three things: an invoice was raised and is unpaid, it was set for the term end, or it went straight to the queue. To act on the new plan, wait for the **applied** hook.
> **On the switch hooks the record shows the old value**
>
> Auto-renewal hands you the service record from **before the change** at the gate and at the event alike. The new state is **a separate parameter** in both. A listener reading the field on the record mistakes a switch-on for a switch-off.
> **Drop a plan you would refuse**
>
> The upgrade gate refuses an option **after the customer picked it**. Writing the same rule into the list filter keeps it off the screen, so nobody tries in vain. Keep the gate for safety and use the filter for **courtesy**.
### Related Articles
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- Invoice and Payment Hooks
- [Service Lifecycle Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
## Service Transfer Hooks
https://dev.wisecp.com/en/service-transfer-hooks
The seven hooks moving a service to a new owner: the request, the recipient's approval, a refusal, and calling it off.
### Overview
A transfer wants **consent from both sides**: the current owner starts it and the recipient approves. A pending record sits between them and either side can call it off.
These hooks **do not tell types apart**: hosting, servers and domains all pass the same flow. Writing a rule meant for domains, check the service type yourself.
### Reference
#### Stopping a transfer request
gateservice.transfer_request
`ClientServices` domains pass here too
Runs where the current owner starts the transfer, before the pending record is written.
Parameters 3
$servicearrayThe service about to move. No type filtering happens: the `type` field can be `domain` too.
$from_idintThe current owner. The account starting the transfer.
$to_idintThe target owner. Resolved from an e-mail address and **confirmed** to be a registered customer.
Return 1
stringA non-empty string **stops** the transfer; the text is thrown as the error and shown to the customer.
Listener PHP
```php
Hook::add('gate:service.transfer_request', 10,
function ($service, $from_id, $to_id) {
// A free developer licence does not move: put your own rule here.
if (Acme::nonTransferable($service))
return 'This service cannot move to another account.';
return null;
});
```
#### Following a transfer request
actionservice.transfer.requested
`ClientServices` the payload, not the record
Runs after the pending transfer record was created. The service is still with **the old owner**.
Parameters 3
$servicearrayThe service about to move, still with its current owner.
$dataarrayThe transfer **payload**: the service name, the sending and receiving sides, the verification token. The parameter in the same slot on the sibling hooks is **the record row itself**; this one is the data inside it. Mixing them up reads empty fields.
$uidintThe id of the owner starting the transfer.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.transfer.requested', 10,
function ($service, $data, $uid) {
// $data IS THE PAYLOAD (not the event row): read its fields directly.
Audit::transferOpened((int) ($service['id'] ?? 0),
(int) ($data['from_id'] ?? 0), (int) ($data['to_id'] ?? 0));
});
```
#### Stopping a transfer approval
gateservice.transfer_approve
`ClientServices` the recipient approves
Runs where the recipient accepts, before ownership moves.
Parameters 3
$servicearrayThe service record about to move.
$from_idintThe current owner.
$to_idintThe target owner.
Return 1
stringA non-empty string **stops** the transfer; the text is thrown as the error and shown to the customer.
Listener PHP
```php
Hook::add('gate:service.transfer_approve', 10,
function ($service, $from_id, $to_id) {
// Check the recipient too: no service moves to an unverified account.
if (!Acme::verifiedAccount($to_id))
return 'The receiving account is not verified.';
return null;
});
```
#### Learning that a transfer completed
actionservice.transfer.approved
`ClientServices` ownership moved
Runs after ownership moved to the new account.
Parameters 4
$serviceIdintThe id of the moved service.
$fromIdintThe previous owner.
$toIdintThe new owner.
$newOwnerarrayThe new owner's record: `id`, `full_name`, `email`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.transfer.approved', 10,
function ($serviceId, $fromId, $toId, $newOwner) {
// Cut the old owner off: the service is no longer theirs.
Acme::revokeAccess($fromId, $serviceId);
Acme::grantAccess($toId, $serviceId);
});
```
#### Following a refused transfer
actionservice.transfer.rejected
`ClientServices` no service record arrives
Runs where the recipient refused the transfer.
Parameters 2
$meintThe account id of the recipient who refused.
$dataarrayThe transfer data: `service_id`, `service_name`, the sending and receiving sides. This hook hands you **no service record**; take the id from here where you need it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.transfer.rejected', 10, function ($me, $data) {
// No service record arrives: take the id from the payload.
Crm::transferRefused((int) ($data['service_id'] ?? 0), (int) ($data['from_id'] ?? 0));
});
```
#### Following a transfer called off
actionservice.transfer.cancelled
`ClientServices` the sender called it off
Runs where the current owner called off a pending transfer.
Parameters 2
$servicearrayThe service record, still with its current owner.
$pendingarrayThe cancelled pending **record row**, holding the recipient details and the verification token. The parameter in the same slot on the request hook was **the payload**; this one is the row, with the data inside it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.transfer.cancelled', 10, function ($service, $pending) {
// Here $pending IS THE RECORD ROW: the payload sits one level in.
$payload = $pending['data'] ?? [];
Audit::transferClosed((int) ($service['id'] ?? 0), (int) ($payload['to_id'] ?? 0));
});
```
#### Following an invitation sent again
actionservice.transfer.resent
`ClientServices` the same record
Runs where the owner sent the transfer invitation again. The pending record **does not change**; only the message is repeated.
Parameters 2
$servicearrayThe service record.
$pendingarrayThe pending transfer record.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.transfer.resent', 10, function ($service, $pending) {
// It repeats: hold back the resends on your own side.
Acme::countResend((int) ($service['id'] ?? 0));
});
```
### Pitfalls
> **The same slot carries two different things**
>
> On the transfer request the second parameter is **the payload**; on the called-off and resent hooks the same slot carries **the record row**, with the payload one level in. Taking one for the other reads **empty fields**: no error, no value.
> **Domains pass this flow too**
>
> The transfer hooks **do not look at** the service type. A rule you wrote for hosting also lands on domain transfers. Targeting one type, check the type field on the service record **in your first line**.
> **The refusal hook hands you no service record**
>
> The refusal hook hands you the refusing account and the transfer data alone; there is **no service record**. A listener used to the other transfer hooks looks for the service name and finds nothing. Take the id from **the payload** and read the record yourself.
> **Two gates guard two different sides**
>
> The request gate guards the **sending** side and the approval gate the **receiving** one. "This service cannot move" belongs at the request gate; "this account cannot receive" belongs at the approval gate. Writing both in one place leaves the other end open.
### Related Articles
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Service Lifecycle Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
## Licence Transfer Hooks
https://dev.wisecp.com/en/licence-transfer-hooks
The seven hooks moving a software licence to another account and resetting an installation.
### Overview
A licence transfer is a **separate flow** from a service transfer. It keeps its own record, charges its own fee, and moves along on **e-mail confirmation from both sides**.
Reissuing has nothing to do with transfers: the installation details a licence is tied to are cleared, so the customer can set the software up on **another server**.
### Reference
#### Stopping a licence transfer
gateservice.license_transfer
`LicenseTransfer` the product config arrives
Runs before a licence transfer starts.
Parameters 2
$servicearrayThe service record about to move, with its options decoded.
$lt_configarrayThe product's licence transfer settings: the fee type, which side is invoiced, the limits. Read this when writing your own rule; the operator may have set each product differently.
Return 1
stringA non-empty string **stops** the transfer; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:service.license_transfer', 10, function ($service, $lt_config) {
// A developer licence given free of charge does not move.
if (!empty($service['options']['developer']))
return 'A developer licence cannot move to another account.';
return null;
});
```
#### Changing the transfer fee
filterservice.license_transfer_fee
`Hook::runRefs` by reference
Runs after the transfer fee was worked out, before the invoice is raised.
Parameters 3
$feearrayrefThe fee as worked out: `type`, `amount`, `currency_id`, `basis`, `base_amount`, `base_currency_id`. For the percentage type the base is the product's current one-time price (`basis` = `product_price`); it falls back to the service amount only when the product has no active one-time price. Zeroing the amount makes the transfer free.
$servicearrayThe service moving, with its amount and currency.
$lt_configarrayThe product's fee settings.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.license_transfer_fee', 10,
function (&$fee, $service, $lt_config) {
// Charge nothing where both sides are the same company.
if (Acme::sameCompany($service)) $fee['amount'] = 0.0;
});
```
#### Learning that a transfer started
actionservice.license_transfer_started
`LicenseTransfer` confirmation is pending
Runs after the transfer record was created. The licence has **not moved yet**.
Parameters 4
$transfer_idintThe id of the created transfer record.
$service_idintThe id of the service moving.
$transferor_idintThe current owner.
$transferee_idintThe target owner.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.license_transfer_started', 10,
function ($transfer_id, $service_id, $transferor_id, $transferee_id) {
// The licence has NOT moved: it waits on both sides confirming.
Audit::licenseTransfer('started', $transfer_id, $service_id);
});
```
#### Following one side confirming
actionlicense.transfer.verified
`LicenseTransfer` it runs twice
Runs where one side confirmed by e-mail. It runs **twice per transfer**.
Parameters 2
$transferarrayThe transfer record as it stands after the confirmation.
$partystringThe side that confirmed: `transferor` (the sender) or `transferee` (the recipient). Read which side from here, since the hook runs twice.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:license.transfer.verified', 10, function ($transfer, $party) {
// The hook runs TWICE: react to the recipient's confirmation alone.
if ($party === 'transferee') Crm::licenseAccepted($transfer['id'] ?? 0);
});
```
#### Learning that a transfer completed
actionservice.license_transfer.completed
`LicenseTransfer` a freshly read record
Runs after the licence moved to its new owner.
Parameters 2
$transfer_idintThe id of the transfer record.
$transferarrayThe **freshly read** transfer row: its status is complete and the completion time is filled in. The cache was bypassed, so the values are current.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.license_transfer.completed', 10,
function ($transfer_id, $transfer) {
// The record was read afresh: status and time are current.
Acme::licenseMoved((int) ($transfer['owner_id'] ?? 0), $transfer);
});
```
#### Following a licence reissue
actionservice.license_reissued
`ClientServices` the installation was cleared
Runs after the licence's installation binding was cleared, so the customer can set the software up on another server.
Parameters 2
$servicearrayThe service record from **before** the reset. Its installation and address fields still hold the **old** values, which is how you learn the previous server.
$uidint**Always the service owner**. Not the person who acted: a sub-user or a staff member may have triggered it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.license_reissued', 10, function ($service, $uid) {
// The old installation is STILL on the record: you see the previous one.
Acme::forgetInstall($service['options']['install'] ?? '');
});
```
#### Following a licence update
actionservice.license_updated
`AdminServices` the licence fields were saved
Runs after an operator saved the service's Management tab and something about the licence changed. Anything holding that licence elsewhere is now stale. Bring your own record up to date here.
Watched fields: the key, the domain, the IP, the version and the licence parameters. Nothing fires when none of them moved. The save already happened, so nothing you return is read.
Parameters 3
$serviceIdintThe service that was saved.
$changesarrayOnly what moved, as `field => ['old' => …, 'new' => …]`. Keys: `key`, `domain`, `ip`, `version`, `parameters`.
$servicearrayThe service record from **before** the save. Read it afresh if you need the stored row.
Reading `$changes['key']` 3
old emptycreationThe key was issued for the first time. Create your record rather than moving one.
both filledmoveFind your record by the old key and put it on the new one.
new emptyclearedThe operator emptied the field. The key was already handed out, so deleting the remote record is usually wrong.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.license_updated', 10,
function ($serviceId, $changes, $service) {
// The key did not move: something else did, so just republish.
if (!isset($changes['key'])) return Acme::republish((int) $serviceId);
$old = (string) $changes['key']['old'];
$new = (string) $changes['key']['new'];
if ($new === '') return; // cleared, not deleted
$old === ''
? Acme::register((int) $serviceId, $new) // issued for the first time
: Acme::rekey($old, $new); // moved onto a new key
});
```
#### Following a licence report
actionservice.license_report_submitted
`ClientServices` a customer report
Runs where a customer submitted a report about their licence.
Parameters 2
$servicearrayThe service the report is about.
$uidintThe service owner's id.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.license_report_submitted', 10, function ($service, $uid) {
Ops::queue('license-report', (int) ($service['id'] ?? 0));
});
```
#### Following a transfer ending
actionservice.license_transfer_cancelled
`LicenseTransfer` three endings
Runs when a licence transfer comes to an end. Three separate endings land here: cancelled, rejected and timed out.
Parameters 3
$transfer_idintThe id of the transfer that ended.
$statusstringWhich ending: `cancelled`, `rejected` or `expired`.
$reasonstringThe reason code, such as an admin cancelling or verification running out of time.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.license_transfer_cancelled', 10,
function ($transfer_id, $status, $reason) {
// Lift the transfer lock on the licence server.
Acme::unlockTransfer($transfer_id);
});
```
#### Following verification being sent again
actionservice.license_transfer.verification_resent
`ClientLicenseTransfer` to waiting parties
Runs when the transfer verification emails go out again. They reach only the parties who have **not verified yet**; nobody who confirmed is written to twice.
Parameters 3
$servicearrayThe record of the service being transferred. The transfer is not done: the service still sits with its current owner.
$activearrayThe live transfer record, with its id and status.
$pendingarrayThe list of parties the mail went to again.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.license_transfer.verification_resent', 10,
function ($service, $active, $pending) {
// Nudge over a second channel, only the parties still waiting.
foreach ($pending as $party) Acme::remind($party, (int) ($active['id'] ?? 0));
});
```
#### Stopping a software domain change
gateservice.software_domain_change
`ClientServices` before the write
Runs while a customer changes the domain their licence is bound to, after the core checks pass and before anything is written.
Parameters 4
$servicearrayThe service record **as it was before the change**.
$oldstringThe domain currently bound; empty when none was ever set.
$domainstringThe requested domain, **already normalised**: lower case, leading www dropped. This is not the raw form value; write your check against this.
$uidintThe account that owns the service.
Return 1
string|null**A non-empty text blocks the change** and is shown to the customer. When blocked, neither the domain is written nor the change hook fires.
Listener PHP
```php
Hook::add('gate:service.software_domain_change', 10,
function ($service, $old, $domain, $uid) {
// Apply your own block list.
if (Acme::blockedDomain($domain)) return 'This domain cannot hold a licence.';
return null;
});
```
#### Following a software domain change
actionservice.software_domain_changed
`ClientServices` after the write
Runs once the bound domain of a licence is saved. This is where you tell the licence server.
Parameters 4
$servicearrayThe service record.
$oldstringThe previous domain; empty on a first binding.
$domainstringThe newly bound domain.
$uidintThe owning account.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.software_domain_changed', 10,
function ($service, $old, $domain, $uid) {
Acme::rebindLicence((int) ($service['id'] ?? 0), $domain);
});
```
### Pitfalls
> **The confirmation hook runs twice per transfer**
>
> The sender and the recipient confirm separately, and the hook runs **on both**. A listener reacting without reading the side does its work twice. Check the party value **in your first line**.
> **On the reissue hook the installation is the OLD one**
>
> The hook hands you the service record from **before** the reset: the installation and address fields point at the old server. That is not a fault but **your only chance**: do whatever you need with the old installation here, because the value is about to go.
> **The owner and the person acting are not the same**
>
> The id on the reissue hook is **always the service owner**. A sub-user or a staff member may have triggered it, and that id **never reaches** this hook. "Who did this" cannot be answered from here.
> **A licence transfer is not a service transfer**
>
> The two flows look alike and use **separate hooks**: a licence transfer has a record of its own, a fee of its own and e-mail confirmation from both sides. A system listening to the service transfer hooks **never sees** a licence one.
### Related Articles
- [Service Transfer Hooks](https://dev.wisecp.com/en/service-transfer-hooks)
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- Invoice and Payment Hooks
## Service Detail Hooks
https://dev.wisecp.com/en/service-detail-hooks
The eight hooks behind what a customer sees on a service detail: the page data, the cards, the tools, add-ons and metrics.
### Overview
The service detail is the screen a customer looks at most, and much of it comes from **the module**: the cards, the tools, the capabilities. The filters here catch that output before it reaches the screen.
The second group is add-ons. An add-on has a **status flow of its own** and moves separately from the parent service: bought on its own, invoiced on its own, suspended on its own.
### Reference
#### Changing the detail page data
filterservice.detail_data
`ClientServices` the whole page
Runs after the detail page's whole template data was built.
Parameters 2
$dataarrayref**All** the data going to the page. The widest place to step in: add your own key without breaking the ones there.
$servicearrayThe service in view.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.detail_data', 10, function (&$data, $service) {
// Add your own data without disturbing the keys already there.
$data['acme_health'] = Acme::health((int) ($service['id'] ?? 0));
});
```
#### Changing the dashboard cards
filterservice.dashboard.cards
`ServerModule` module output
Runs after the module's card definitions were built, before they reach the screen.
Parameters 2
$cardsarrayrefThe card definitions. You can add, drop or reorder them.
$moduleServerModuleThe service's module object. Use it to tell modules apart; a rule may not suit them all.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.dashboard.cards', 10, function (&$cards, $module) {
// Put your card where it belongs rather than at the end.
array_splice($cards, 1, 0, [Acme::usageCard()]);
});
```
#### Changing the tool list
filterservice.dashboard.tools
`ServerModule` a grouped list
Runs after the module's tool list was built.
Parameters 2
$toolsarrayrefThe grouped tool list: each group carries its own details and tools. It is not a flat list; you reach into the group.
$moduleServerModuleThe service's module object.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.dashboard.tools', 10, function (&$tools, $module) {
// The list IS GROUPED: reach the tools inside a group.
foreach ($tools as &$group)
$group['tools'] = array_filter($group['tools'] ?? [],
fn ($t) => ($t['key'] ?? '') !== 'rebuild');
});
```
#### Changing the domain capabilities
filterservice.detail_tabs_capabilities
`ClientDomains` it opens the tabs
Runs after it was decided which capabilities the domain detail tabs show.
Parameters 3
$capabilitiesarrayrefThe capability marks: DNS records, mail forwarding and the like. Every mark you write here is **carried back** to the screen's matching key: switching one off hides that tab.
$servicearrayThe domain service in view.
$moduleobject|nullThe provider module — it **can be empty**. On a domain with no module it arrives as `null`, so check before calling anything on it.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:service.detail_tabs_capabilities', 10,
function (&$capabilities, $service, $module) {
if ($module === null) return; // a domain with no module
// Switching a mark off hides that tab on the screen.
$capabilities['has_email_forwarding'] = Acme::mailAllowed($service);
});
```
#### Learning that an add-on opened
actionservice.addon.created
`Services` a separate invoice
Runs after an add-on was added to a service.
Parameters 5
$addonRecordIdintThe id of the created add-on record.
$serviceIdintThe id of the parent service.
$addonIdintThe id of the add-on product. `0` means this is a **domain add-on**, which has no entry in the product catalogue.
$invoiceIdintThe id of the raised invoice, or `0` where there is none.
$totalAmountfloatThe total charged for the add-on.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.addon.created', 10,
function ($addonRecordId, $serviceId, $addonId, $invoiceId, $totalAmount) {
// An addonId of 0 marks a DOMAIN add-on, not a product.
if ($addonId === 0) return;
Crm::addonSold($serviceId, $addonId, (float) $totalAmount);
});
```
#### Following an add-on status
actionservice.addon.status_changed
`Services` one array parameter
Runs after an add-on's status changed.
Parameters 1
$payloadarrayA single array: `service`, `addon`, `addon_id`, `old_status`, `new_status`, `user_id`. An add-on's status is **independent** of the parent: one can be suspended while the other runs.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.addon.status_changed', 10, function ($payload) {
// ONE array arrives; the old and new status sit inside it.
if (($payload['new_status'] ?? '') === 'suspended')
Acme::addonOff((int) ($payload['addon_id'] ?? 0));
});
```
#### Stopping a metric switch
gateservice.metric_toggle
`ClientServices` nothing is written
Runs while a customer switches a usage metric on or off. Stopping it means nothing reaches **the database or the module**.
Parameters 4
$servicearrayThe service record.
$metricKeystringThe metric key. Defined in the product's metric settings.
$enableboolThe state being asked for.
$labelstringThe metric's display label. Handed to you ready for your error message.
Return 1
stringA non-empty string **stops** the switch; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:service.metric_toggle', 10,
function ($service, $metricKey, $enable, $label) {
// The label arrives ready: write the message with the name they see.
if (!$enable && Acme::metricRequired($metricKey))
return $label . ' cannot be switched off.';
return null;
});
```
#### Following a metric switch
actionservice.metric_toggled
`ClientServices` it landed
Runs after the metric state was written.
Parameters 3
$servicearrayThe service record.
$metricKeystringThe metric key.
$enableboolThe new state that was written.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.metric_toggled', 10, function ($service, $metricKey, $enable) {
// A metric switched off can still be billed: set your own counter.
Acme::metricState((int) ($service['id'] ?? 0), $metricKey, (bool) $enable);
});
```
#### Following a customer opening the detail page
actionservice.detail.viewed
`website/services` on every opening
Runs when a customer opens the management page of their own service. Ownership and access checks are already behind you.
Parameters 2
$servicearrayThe loaded service record.
$serviceIdintThe id of the service.
Return 1
voidThe return is ignored. To change what the page shows, use the detail data filter rather than this hook.
Listener PHP
```php
Hook::add('action:service.detail.viewed', 10, function ($service, $serviceId) {
// Keep it light: the customer is waiting for the page.
Acme::touchLastSeen($serviceId);
});
```
#### Following an admin opening the detail page
actionservice.viewed
`admin/services` on every opening
Runs when an administrator opens a service detail. It carries the **same data** as its customer-side twin; only the person looking differs.
Parameters 2
$servicearrayThe loaded service record.
$service_idintThe id of the service.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.viewed', 10, function ($service, $service_id) {
// Pull the live status from the remote panel ahead of time.
Acme::prefetchStatus($service_id);
});
```
#### Stopping a file download
gateservice.file_download
`website/services` three flows
Runs before a customer downloads a service file. All three flows pass through here: requirement attachment, software package and delivery file.
Parameters 2
$kindstringWhich flow: `requirement`, `package` or `delivery`.
$ctxarrayContext. Shared: `user_id`, `service_id`. The flow adds file name, version and record id.
Return 1
mixed**A filled return blocks the download**: the answer becomes a 403 at once. The trap: this endpoint returns a raw file, so your return **never reaches the customer**. Unlike other gates no reason appears on screen; record it yourself. An empty return lets the download go on.
Listener PHP
```php
Hook::add('gate:service.file_download', 10, function ($kind, $ctx) {
if ($kind !== 'package') return null;
// Block when the quota is used up; no reason reaches the screen, so log it.
if (Acme::quotaExceeded((int) ($ctx['user_id'] ?? 0))) {
Acme::log('download quota used up', $ctx);
return true;
}
return null;
});
```
#### Changing which file is served
filterservice.file_download.source
`website/services` passed by link
Runs before the file is handed to the stream. You can build a package with install-specific keys inside it, or send the download to an address of your own.
Parameters 2
$sourcearrayby linkWhat will be served: `path` (full path on disk), `name` (the saved name), `link` (outside address), `cleanup`.
$ctxarrayby linkContext: `kind`, `user_id`, `service_id`, the service record and product id.
Return 1
voidThe return is ignored; you write over the source. A filled path is sent; an empty path with an outside address redirects there; neither gives a 404. Set `cleanup` and **only the file** is removed afterwards, not the folder above it.
Listener PHP
```php
Hook::add('filter:service.file_download.source', 10, function (&$source, &$ctx) {
if (($ctx['kind'] ?? '') !== 'package') return;
// Build a package with the install key inside, then have it removed.
$source['path'] = Acme::buildPackage((int) ($ctx['service_id'] ?? 0));
$source['name'] = 'acme-setup.zip';
$source['cleanup'] = true;
});
```
#### Stopping a billing profile assignment
gateservice.billing_profile_assign
`ClientServiceBilling` before the write
Runs while a customer assigns a billing profile to a service, before anything is written. Domains pass through this gate too.
Parameters 3
$servicearrayThe service or domain record.
$profileIdintThe id of the profile being assigned. A **zero** means the override is being dropped and the account default restored.
$uidintThe account that owns both the profile and the service.
Return 1
string|null**A non-empty text blocks the assignment** and the text is shown to the customer as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:service.billing_profile_assign', 10,
function ($service, $profileId, $uid) {
// Do not allow profile changes while an account is frozen.
if (Acme::frozen($uid)) return 'Your account is under review, so this cannot change.';
return null;
});
```
#### Following a billing profile assignment
actionservice.billing_profile_assigned
`ClientServiceBilling` after the write
Runs once the assignment is saved. The gate is behind you and the value is written.
Parameters 4
$servicearrayThe service or domain record.
$profileIdintThe assigned profile; a zero means the default came back.
$profileNamestringThe visible name: a company or person, or "Default" when the override was dropped.
$uidintThe owning account.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:service.billing_profile_assigned', 10,
function ($service, $profileId, $profileName, $uid) {
Acme::syncAccounting((int) ($service['id'] ?? 0), $profileId);
});
```
### Pitfalls
> **The tool list arrives grouped**
>
> The tool filter hands you **a list of groups**, not a flat list, with each group holding its own tools. A listener walking it directly finds no tools, because every element it holds is a **group**.
> **The module can be empty on the capability filter**
>
> On the domain capability filter the third parameter **can be empty**: some domains have no module. Calling a method without checking takes the page down. Every mark you write here is also **carried back** to the screen, so switching one off makes that tab vanish.
> **An add-on is independent of its parent**
>
> An add-on carries its own status, its own invoice and its own suspend flow. The parent can be running while the add-on is suspended, or the other way round. Reading the parent's status and assuming the add-on is open leaves **an unpaid capability** switched on.
> **A zero add-on id means a domain**
>
> Where the product id on the add-on event is `0`, this is a **domain add-on** (DNS management, privacy, forwarding) with no entry in the product catalogue. A listener reaching for a product finds **nothing** here.
### Related Articles
- [Service Module Hooks](https://dev.wisecp.com/en/service-module-hooks)
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- [Hooks on the Customer Site](https://dev.wisecp.com/en/hooks-on-the-customer-site)
# Hooks / Domains
## Domain Acquisition Hooks
https://dev.wisecp.com/en/domain-acquisition-hooks
The eight hooks on the path to the domain provider: the gates before a register, transfer or renew call, and the events behind them.
### Overview
Getting a domain is a **paid and irreversible** call. Once the provider opened the registration there is no taking it back, so every step of this path has a gate in front of it and an event behind it.
Gates run **before** the call and can stop it. Events run **after**, separately for success and for failure. Below is the full contract of all eight: which values arrive, in what order, and what you have to return.
### Reference
#### Stopping a register or transfer request
gatedomain.create
`RegistrarModule::create()` before a paid call
Runs immediately before the register or transfer request reaches the provider; the method was checked and the arguments are not built yet.
Parameters 3
$servicearrayThe service record being provisioned. Owner, product and term live here.
$optionsarrayThe parameters going to the provider: `sld`, `tld`, `year`, `dns`, `whois`, `tcode`.
$methodstringThe method about to run: `register` or `transfer`. With a transfer code present it is a transfer.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the provider is never called. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.create', 10, function ($service, $options, $method) {
if ($method === 'transfer') return null; // leave transfers alone
$years = (int) ($options['year'] ?? 1);
if ($years > 5) return 'We register at most 5 years at a time.';
return null;
});
```
#### Taking the register or transfer result
actiondomain.created
`RegistrarModule::create():122` once per call
Runs right after the provider call returned. It is **no promise of success**: the result value can carry a failure too.
Parameters 3
$servicearrayThe service record being provisioned.
$resultarray|boolWhat the provider returned: a config and status array, or `false` on failure. This is the value to read first.
$methodstringThe method that ran: `register` or `transfer`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.created', 10, function ($service, $result, $method) {
if ($result === false) return; // failure has its own hook
if ($method === 'register') Dns::applyTemplate($service['name'] ?? '');
});
```
#### Catching a failed registration
actiondomain.register_failed
`RegistrarModule::create()` on failure only
Runs where the provider call came back a failure, right after the previous hook.
Parameters 4
$servicearrayThe service record the provisioning was attempted for.
$optionsarrayThe parameters that were sent to the provider.
$methodstringThe method that ran.
$errorstringThe error message the module reported. It can be empty.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.register_failed', 10,
function ($service, $options, $method, $error) {
Ops::alert('domain-provision', [
'name' => $service['name'] ?? '',
'method' => $method,
'error' => $error ?: 'the provider gave no reason',
]);
});
```
#### Stopping a renewal request
gatedomain.renew
`RegistrarModule::renew():144` before a paid call
Runs before the renewal request reaches the provider.
Parameters 2
$servicearrayThe service being renewed. Its end date and term are in here.
$optionsarrayThe renewal parameters: `sld`, `tld`, `year`.
Return 1
stringA non-empty string stops the renewal. This hook is also on the path of overnight jobs — stopping it leaves the domain unrenewed.
Listener PHP
```php
Hook::add('gate:domain.renew', 10, function ($service, $options) {
// Renewing spends money where the customer already asked to cancel.
if (Acme::cancelRequested((int) ($service['id'] ?? 0)))
return 'A cancellation is open, so the renewal was stopped.';
return null;
});
```
#### Learning that a renewal landed
actiondomain.renewed
`Invoices::handle_renewal_domain_paid():1040` from the payment path
Runs after a paid renewal item extended the end date and the provider was updated.
Parameters 1
$servicearrayThe renewed service record. The end date is the **new** one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.renewed', 10, function ($service) {
ExternalDns::syncExpiry($service['name'] ?? '', $service['duedate'] ?? '');
});
```
#### Catching a failed renewal
actiondomain.renew_failed
`RegistrarModule::renew()` expiry at risk
Runs where the provider's renewal call came back a failure.
Parameters 3
$servicearrayThe service the renewal was attempted for.
$optionsarrayThe renewal parameters.
$errorstringThe error message the module reported; it can be empty.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.renew_failed', 10, function ($service, $options, $error) {
// The customer paid and the domain did not renew: this wants a person.
Ops::page('domain-renew-failed', $service['name'] ?? '', $error);
});
```
#### Following a transfer through
actiondomain.transfer.completed
`Services::check_transfer_status():686` the service is live now
Runs after the provider reported the transfer done, the service went live and word was sent.
Parameters 1
$servicearrayThe service record **read afresh** after activation; its start and end dates are current.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.transfer.completed', 10, function ($service) {
ExternalDns::provision($service['name'] ?? '');
});
```
#### Catching a failed transfer check
actiondomain.transfer.failed
`Services::check_transfer_status():659` the check repeats
Runs where the provider's transfer status check failed, right before the error is thrown.
Parameters 1
$servicearrayThe domain service whose transfer check failed.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.transfer.failed', 10, function ($service) {
// The check repeats on a schedule: alert on a streak, not on one failure.
if (Acme::failStreak((int) ($service['id'] ?? 0)) >= 3)
Ops::alert('domain-transfer-stuck', $service['name'] ?? '');
});
```
#### Following the transfer code being saved
actiondomain.transfer_authcode_saved
`ClientDomains` secret value
Runs after a customer saves the authorisation code for an incoming transfer. This is where you tell the outside system that drives the transfer.
Parameters 2
$servicearrayThe domain record.
$codestringThe saved authorisation code, **in the clear**. Whoever holds this code can move the domain elsewhere: keep it out of your own records and out of your logs.
Return 1
voidThe return is ignored. The code is already saved.
Listener PHP
```php
Hook::add('action:domain.transfer_authcode_saved', 10, function ($service, $code) {
// Carry the fact that a code arrived, NOT the code itself.
Acme::transferReady((int) ($service['id'] ?? 0), $service['name'] ?? '');
});
```
### Pitfalls
> **The result hook is no promise of success**
>
> The register hook runs when the provider call **returned**, not when it succeeded. Where the second parameter is `false` the work **did not land**. Setting up DNS or telling the customer "your domain is ready" without checking treats a record that does not exist as real.
> **The renewal gate is also on the overnight path**
>
> Renewals do not run from an operator's hand alone: the post-payment flow and scheduled jobs pass the same gate. A condition you put there can leave a domain **unrenewed** with nobody noticing. Record it somewhere when you stop the gate; a silent veto is the costliest kind.
> **The transfer check repeats**
>
> The transfer status is asked on a schedule, and every failed check runs the failure hook **again**. A listener that alerts on each call produces dozens of messages for one pending transfer. Count the streak rather than reacting to a single failure.
> **The gate is the last stop before a paid call**
>
> The register and renew gates are the **last** point before money is spent. Fraud checks, quota limits and premium confirmations belong here. The same check made after the call does not bring the money back.
### Related Articles
- [Service Lifecycle Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- Invoice and Payment Hooks
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
## Domain DNS Hooks
https://dev.wisecp.com/en/domain-dns-hooks
The ten hooks setting where a domain points: name servers, DNS records, DNSSEC and child name servers.
### Overview
What these four surfaces share: they all work **live**. Reads and writes alike send a real request to the provider, and our record is only a mirror.
Learn the pattern once and all four follow it: a gate in front of a write, an event behind it, and on the read side a filter handing you the list by reference.
### Reference
#### Stopping a name server write
gatedomain.nameservers_save
`AdminServices::save_nameservers()` `ClientDomains:197` from both paths
Runs before the name server list is written to the provider, with the input already checked. **Both** paths, panel and customer panel, pass through here.
Parameters 2
$servicearrayThe domain service record.
$dnsarrayThe name server list about to be written. The non-empty `ns1..ns4` values, in order.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the provider is never called. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.nameservers_save', 10, function ($service, $dns) {
// Changing name servers mid-transfer breaks the transfer.
if (($service['status'] ?? '') === 'transfer')
return 'Name servers cannot change while a transfer runs.';
return null;
});
```
#### Following a name server change
actiondomain.nameservers_saved
`AdminServices::save_nameservers()` on success only
Runs after the provider call succeeded, the values landed on the service and the activity was recorded.
Parameters 2
$servicearrayThe domain service record.
$dnsarrayThe list that was written to the provider.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.nameservers_saved', 10, function ($service, $dns) {
DnsMonitor::resync($service['name'] ?? '', $dns);
});
```
#### Stopping a DNS record change
gatedomain.dns_record_save
`AdminServices::save_dns_record()` `AdminServices::delete_dns_record()` three actions, one hook
Runs before a DNS record changes at the provider. Adding, updating and deleting **all three** pass here, and the third parameter says which.
Parameters 3
$servicearrayThe domain service record.
$recordarrayThe record being worked on: `type`, `name`, `value`, `identity`. On an update also `ttl` and `priority`.
$taskstringThe action: `create`, `update` or `delete`.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the provider is never called. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.dns_record_save', 10, function ($service, $record, $task) {
$type = strtoupper((string) ($record['type'] ?? ''));
// Stop a delete that cuts the mail flow; adds and updates carry on.
if ($task === 'delete' && $type === 'MX')
return 'An MX record cannot be deleted; change the mail settings first.';
return null;
});
```
#### Following a DNS record change
actiondomain.dns_record_saved
`AdminServices::save_dns_record()` on success only
Runs after the change at the provider finished successfully.
Parameters 3
$servicearrayThe domain service record.
$recordarrayThe record that was worked on.
$taskstringThe action that ran.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.dns_record_saved', 10, function ($service, $record, $task) {
Audit::dns($service['name'] ?? '', $task, $record);
});
```
#### Stopping a DNSSEC record action
gatedomain.dnssec_save
`AdminServices` create and delete
Runs before a DS record is created or deleted at the provider.
Parameters 3
$servicearrayThe domain service record.
$recordarrayThe DS record: `digest`, `key_tag`, `digest_type`, `algorithm`. On a delete also `identity`.
$verbstring`create` or `delete`.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the provider is never called. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.dnssec_save', 10, function ($service, $record, $verb) {
// Deleting the last DS record switches validation off entirely.
if ($verb === 'delete' && Acme::dsCount((int) ($service['id'] ?? 0)) <= 1)
return 'The last DNSSEC record cannot be deleted.';
return null;
});
```
#### Following a DNSSEC change
actiondomain.dnssec_saved
`AdminServices` on success only
Runs after the DS record landed at the provider.
Parameters 3
$servicearrayThe domain service record.
$recordarrayThe DS record that was handled.
$verbstringThe action that ran.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.dnssec_saved', 10, function ($service, $record, $verb) {
Audit::dnssec($service['name'] ?? '', $verb, $record['key_tag'] ?? '');
});
```
#### Stopping a child name server action
gatedomain.child_ns_save
`ClientDomains` create and delete
Runs before a child name server is added at the provider or removed from it.
Parameters 4
$servicearrayThe domain service record.
$hoststringThe fully qualified name, such as `ns1.example.com`.
$ipstringThe address behind the name. It can arrive empty on a delete.
$verbstring`create` or `delete`.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the provider is never called. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.child_ns_save', 10, function ($service, $host, $ip, $verb) {
if ($verb === 'delete') return null;
// Do not glue a name to an address outside your own block.
if (!Acme::ownsIp($ip)) return 'That address is not ours.';
return null;
});
```
#### Following a child name server change
actiondomain.child_ns_saved
`ClientDomains` on success only
Runs after the child name server landed at the provider.
Parameters 4
$servicearrayThe domain service record.
$hoststringThe name that was handled.
$ipstringThe address behind it.
$verbstringThe action that ran.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.child_ns_saved', 10, function ($service, $host, $ip, $verb) {
Ipam::glue($verb, $host, $ip);
});
```
#### Changing the child name server list
filterdomain.child_ns_list
`Hook::runRefs` by reference
Runs after the list read from the provider was normalised, before it reaches the screen.
Parameters 2
$listarrayrefThe normalised list: every row carries `ns` and `ip`. Keep the shape; the screen draws to this contract.
$servicearrayThe domain service record.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.child_ns_list', 10, function (&$list, $service) {
// Sort without breaking the shape: the screen wants ns and ip keys.
usort($list, fn ($a, $b) => strcmp($a['ns'] ?? '', $b['ns'] ?? ''));
});
```
#### Changing the DNSSEC list
filterdomain.dnssec_records
`Hook::runRefs` by reference
Runs after the DS records read from the provider were normalised.
Parameters 2
$recordsarrayrefThe normalised records: `identity`, `digest`, `key_tag`, `digest_type`, `algorithm`. A delete sends `identity` back; do not drop it.
$servicearrayThe domain service record.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.dnssec_records', 10, function (&$records, $service) {
// KEEP the identity field: a delete targets the record with it.
$records = array_values(array_filter($records,
fn ($r) => (int) ($r['algorithm'] ?? 0) !== 5)); // hide the old algorithm
});
```
### Pitfalls
> **One gate carries three actions**
>
> The DNS record gate is the **same** hook for adding, updating and deleting. Without reading the third parameter, a rule you wrote to "stop deletes" stops adds as well. The same holds for the DNSSEC and child name server gates, where the action sits in the fourth parameter.
> **Keep the shape in list filters**
>
> Read filters hand you the array the screen **draws directly**. Renaming a key or dropping `identity` breaks more than the list: it leaves **the delete call** without a target, because the record is found by that field.
> **The gate is on both paths**
>
> The name server gate sits on the panel path and the customer path alike. A rule written as "the customer should not" stops **the operator** too. To tell the paths apart, look at the calling context rather than at the service record.
> **Propagation is not instant**
>
> The event says the provider **accepted** the change, not that the world sees it. Propagation takes minutes. A listener acting on the new value gets **the old answer** where it checks straight away.
### Related Articles
- [Domain Acquisition Hooks](https://dev.wisecp.com/en/domain-acquisition-hooks)
- Domain Hooks
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
## Domain Contact Hooks
https://dev.wisecp.com/en/domain-contact-hooks
The ten hooks over the person behind a domain, its privacy and its transfer lock.
### Overview
These three go together. Contact details are what the registry **requires**, privacy hides them from outside, and the transfer lock stops the name moving without permission.
All three are written live to the provider. Saved contact profiles, on the other hand, live **on our side**: they are templates kept so a customer types the same details once, and they carry hooks of their own.
### Reference
#### Stopping a contact write
gatedomain.contacts_save
`AdminServices` all four roles
Runs before the contact details are written to the provider.
Parameters 2
$servicearrayThe domain service record.
$whoisarrayThe four roles: `registrant`, `administrative`, `technical`, `billing`. Each role carries name, surname, e-mail, phone and address fields.
Return 1
stringA non-empty string **stops** the action and the text is thrown as the error. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.contacts_save', 10, function ($service, $whois) {
// The registrant e-mail cannot change before it is verified.
$mail = (string) ($whois['registrant']['EMail'] ?? '');
if ($mail !== '' && !Acme::verified($mail))
return 'The registrant e-mail wants verifying first.';
return null;
});
```
#### Following a contact change
actiondomain.contacts_saved
`AdminServices` on success only
Runs after the contact details reached the provider.
Parameters 2
$servicearrayThe domain service record.
$whoisarrayThe four roles as written to the provider.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.contacts_saved', 10, function ($service, $whois) {
Audit::whois($service['name'] ?? '', $whois['registrant']['EMail'] ?? '');
});
```
#### Stopping a privacy change
gatedomain.privacy_change
`AdminServices` on and off
Runs before privacy changes at the provider.
Parameters 2
$servicearrayThe domain service record.
$statusstringThe state being asked for: `enable` or `disable`. What was asked, not what it became.
Return 1
stringA non-empty string **stops** the action and the text is thrown as the error. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.privacy_change', 10, function ($service, $status) {
// Some extensions offer no privacy at all.
if ($status === 'enable' && Acme::noPrivacyTld($service['name'] ?? ''))
return 'This extension offers no privacy.';
return null;
});
```
#### Following the privacy state
actiondomain.privacy_changed
`AdminServices` the new state is a bool
Runs after privacy changed at the provider.
Parameters 2
$servicearrayThe domain service record.
$enabledboolThe new state: `true` means privacy is on. Unlike the text value at the gate, this one is a boolean.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.privacy_changed', 10, function ($service, $enabled) {
Billing::privacyFee((int) ($service['id'] ?? 0), (bool) $enabled);
});
```
#### Stopping a transfer lock change
gatedomain.transfer_lock_change
`AdminServices` on and off
Runs before the lock changes at the provider.
Parameters 2
$servicearrayThe domain service record.
$statusstringThe state being asked for: `enable` to lock, `disable` to open.
Return 1
stringA non-empty string **stops** the action and the text is thrown as the error. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.transfer_lock_change', 10, function ($service, $status) {
// Opening the lock is the first step to the name moving away.
if ($status === 'disable' && Acme::recentlyChangedOwner($service))
return 'The lock stays on for 60 days after an owner change.';
return null;
});
```
#### Following the lock state
actiondomain.transfer_lock_changed
`AdminServices` the new state is a bool
Runs after the lock changed at the provider.
Parameters 2
$servicearrayThe domain service record.
$lockedboolThe new state: `true` means locked.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.transfer_lock_changed', 10, function ($service, $locked) {
if (!$locked) Ops::watch('domain-unlocked', $service['name'] ?? '');
});
```
#### Changing the lock state reported
filterdomain.transfer_lock_status
`Hook::runRefs` by reference
Runs before the lock state reaches a screen or an API answer.
Parameters 2
$lockedboolrefThe state about to be reported. Where the provider says nothing, you can fill it in here.
$servicearrayThe domain service record.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.transfer_lock_status', 10, function (&$locked, $service) {
// Fill from our own record where the provider does not know.
if ($locked === null) $locked = Acme::lockMirror((int) ($service['id'] ?? 0));
});
```
#### Stopping a transfer code request
gatedomain.epp_code_get
`AdminServices` the code goes to the owner
Runs before the transfer code is asked of the provider.
Parameters 2
$servicearrayThe domain service record.
$serviceIdintThe service id.
Return 1
stringA non-empty string **stops** the action and the text is thrown as the error. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.epp_code_get', 10, function ($service, $serviceId) {
// The transfer code is the key to the name changing hands.
if (Acme::openDispute($serviceId)) return 'No code while a dispute is open.';
return null;
});
```
#### Following a transfer code request
actiondomain.epp_code_retrieved
`AdminServices` two kinds of value
Runs after the code came back from the provider.
Parameters 2
$servicearrayThe domain service record.
$codestring|boolThe code itself, or `true`. `true` means "the code was not returned, it was e-mailed to the owner".
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.epp_code_retrieved', 10, function ($service, $code) {
// NEVER log the code: it is the key to the name.
Audit::note('epp-requested', $service['name'] ?? '',
$code === true ? 'sent by e-mail' : 'shown on screen');
});
```
#### Stopping a contact profile save
gatedomain.whois_profile_save
`ClientDomains` on our side
Runs before a saved contact profile is written to the database. This one **never reaches** the provider; a profile is a template kept on our side.
Parameters 3
$uidintThe account id owning the profile. An **account** arrives here, not a service.
$informationarrayThe contact fields: `FirstName`, `LastName`, `Company`, `EMail`, `Phone`, address fields.
$profileIdint`0` for a new profile; a value above zero is the id of the one being edited.
Return 1
stringA non-empty string **stops** the action and the text is thrown as the error. `null` or an empty string lets it carry on.
Listener PHP
```php
Hook::add('gate:domain.whois_profile_save', 10,
function ($uid, $information, $profileId) {
if ($profileId > 0) return null; // leave edits alone
if (Acme::profileCount($uid) >= 10) return 'At most 10 profiles are kept.';
return null;
});
```
#### Following a profile save
actiondomain.whois_profile_saved
`ClientDomains` the id is filled in now
Runs after the profile was saved.
Parameters 3
$uidintThe account id.
$profileIdintThe id of the saved profile. Filled in even for a new one.
$informationarrayThe fields that were saved.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.whois_profile_saved', 10,
function ($uid, $profileId, $information) {
Acme::indexProfile($uid, $profileId, $information['EMail'] ?? '');
});
```
### Pitfalls
> **The transfer code is the key to the name**
>
> Anyone holding the code can move the domain to another provider. Do **not** log the value the event hands you, put it in a notification or send it to an outside system. Where the value is `true` the code already went to the owner by e-mail; you do not hold it, and you should not.
> **Text at the gate, a boolean at the event**
>
> The privacy and lock gates hand you **the state asked for as text** (`enable`/`disable`), while the events hand you **the state reached as a boolean**. Mixing them up fails silently: a text value always counts as true.
> **Profile hooks carry an account, not a service**
>
> The first parameter of the saved-profile hooks is an **account id**, not a service record. A listener used to the other domain hooks reaches for `$service['name']` here and finds nothing. A profile belongs to an account, not to a domain.
> **Changing the registrant can trigger verification**
>
> Changing the registrant e-mail starts **re-verification** on most extensions, and an unverified name can be suspended. A listener touching the contact write should be written knowing that; the verification state has a filter of its own.
### Related Articles
- [Domain Acquisition Hooks](https://dev.wisecp.com/en/domain-acquisition-hooks)
- [Domain DNS Hooks](https://dev.wisecp.com/en/domain-dns-hooks)
- Domain Hooks
## Domain Catalogue Hooks
https://dev.wisecp.com/en/domain-catalogue-hooks
The ten hooks running while a customer searches for a name and an operator builds the extension catalogue: availability, suggestions, categories, the price matrix.
### Overview
Selling domains has two sides. On the customer's side there is **the search**: a name is typed, the provider is asked, a result and suggestions come back. On the operator's side there is **the catalogue**: which extensions sell, in which category, at what price.
Every hook here works **by reference**: you are handed an array, you change it, and your return is not read. The shape contract is tight, because the screen and the cart read the output directly.
### Reference
#### Changing the availability answer
filterdomain.availability
`AdminOrders::check_domain():336` a panel order
Runs after the provider's availability answer was worked out, before the response is built.
Parameters 4
$availableboolrefThe availability the provider reported. Setting it to `false` takes the name off sale.
$sldstringThe name itself, without the extension.
$tldstringThe extension.
$check_resultarrayThe provider's raw answer. Read the detail here to justify your decision.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.availability', 10,
function (&$available, $sld, $tld, $check_result) {
// Brand protection: nobody registers our own name.
if (Acme::brandTerm($sld)) $available = false;
});
```
#### Changing the customer search result
filterdomain.client_search_results
`ClientDomain::check():124` already sorted
Runs after the primary result and the suggestions were built, the cart state was applied **and the suggestions were sorted**.
Parameters 2
$responsearrayrefThe whole answer: `status`, `type` (`register` or `transfer`), `currency`, `primary` (the primary result or `null`), `suggestions`. Cart state arrives on each entry as `in_cart`.
$searchContextarrayThe query context: `sld`, `tld`, `transfer`, `ucid` (the display currency).
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.client_search_results', 10,
function (&$response, $searchContext) {
// Sorting already ran: put your suggestion FIRST, not last.
$extra = Acme::suggest($searchContext['sld'] ?? '');
if ($extra) array_unshift($response['suggestions'], $extra);
});
```
#### Changing the featured extensions
filterdomain.spotlight_tlds
`ClientDomain::spotlight_tlds():275` no dot, lower case
Runs after the list from the language file was lower-cased and any leading dot trimmed.
Parameters 1
$tldsarrayrefThe extension list: plain strings, **no dot and lower case** (`["net","org","io"]`). A dot or a capital makes the extension unfindable.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.spotlight_tlds', 10, function (&$tlds) {
$tlds = ['com', 'net', 'co.uk']; // no dot, lower case
});
```
#### Changing the extension categories
filterdomain.tld_categories
`domain::build_categories():86` key and label
Runs after the category keys were matched with their translated labels.
Parameters 1
$outarrayrefThe ordered category list: every row carries `key` and `label`. The key has to match the one on the extension rows; an invented key returns no extensions.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.tld_categories', 10, function (&$out) {
// The key HAS TO MATCH the category list on the extension rows.
$out[] = ['key' => 'local', 'label' => 'Local'];
});
```
#### Changing the extension price table
filterdomain.tld_table
`website/domain` prices resolved
Runs after the extension rows were built and the prices resolved into the display currency.
Parameters 2
$outarrayrefThe extension rows. Each row: `name` (**without a dot**), `categories` (comma-separated keys), the register and renew prices.
$ucidintThe display currency id. The prices are in this currency; give any row you add in the same one.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.tld_table', 10, function (&$out, $ucid) {
// Hide rows without a price so nobody clicks a priceless extension.
$out = array_values(array_filter($out,
fn ($r) => (float) ($r['register'] ?? 0) > 0));
});
```
#### Changing the renewal price
filterdomain.premium_renewal_price
`Invoices::_renewal_pricing_domain()` already converted
Runs after the extension's renewal price was found and the currency conversion and year multiplier applied.
Parameters 4
$renewal_amountfloatrefThe unit price in the target currency. The multiplier is applied already, and what you write here reaches the invoice.
$servicearrayThe domain service being renewed.
$tldarrayThe extension record: `id`, `name`, `min_years`.
$target_currencyintThe currency the amount is in.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.premium_renewal_price', 10,
function (&$renewal_amount, $service, $tld, $target_currency) {
// A premium name renews at the provider's price, not the catalogue's.
$real = Acme::premiumRenewal($service['name'] ?? '', $target_currency);
if ($real > 0) $renewal_amount = $real;
});
```
#### Changing the price matrix before it is saved
filterdomain.pricing_save
`AdminProducts` type by year by currency
Runs after the costs pulled from the provider were turned into prices with the profit rate, before they are written.
Parameters 2
$pricingarrayrefThe price matrix: `[type][year][currency]` → `cost` and `promo`. Types: `register`, `renewal`, `transfer`.
$contextarrayThe context: `module`, `tld`, `cost_cid`, `profit_rate`.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.pricing_save', 10, function (&$pricing, $context) {
// Sell the first year at cost; leave renewals alone.
foreach ($pricing['register'][1] ?? [] as $cid => $row)
$pricing['register'][1][$cid]['promo'] = $row['cost'];
});
```
#### Changing a new extension record
filterdomain.tld_save_data
`AdminProducts` on create only
Runs before a new extension is written to the database.
Parameters 2
$insert_dataarrayrefThe record about to be written: `name`, `module`, `status`, `rank`, `dns_manage`, `forwarding`, `whois_privacy`, `epp_code`.
$extensionstringThe extension being added.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.tld_save_data', 10, function (&$insert_data, $extension) {
// A new extension arrives switched off, so nothing sells without a price.
$insert_data['status'] = 0;
});
```
#### Stopping an extension delete
gatedomain.tld_delete
`AdminProducts` takes it off the catalogue
Runs before an extension is deleted from the catalogue.
Parameters 2
$extensionstringThe extension about to be deleted.
$tldarrayThe extension record.
Return 1
stringA non-empty string **stops** the delete; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:domain.tld_delete', 10, function ($extension, $tld) {
// Deleting an extension with sold names leaves those records orphaned.
if (Acme::soldCount((int) ($tld['id'] ?? 0)) > 0)
return 'Names are sold on this extension; it cannot be deleted.';
return null;
});
```
#### Following a new extension
actiondomain.tld_created
`AdminProducts` the id is filled in
Runs after the extension was created in the catalogue.
Parameters 3
$tld_idintThe id of the created record.
$extensionstringThe extension name.
$registrarstringThe provider module assigned. Without a module chosen, an empty key arrives.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.tld_created', 10,
function ($tld_id, $extension, $registrar) {
Ops::note('tld-added', $extension . ' -> ' . ($registrar ?: 'no module'));
});
```
#### Taking over a single lookup
filterdomain.available
`Registrar::check` takes over by returning
Runs before the availability question is asked for one extension. Return a filled answer and the system asks neither WHOIS nor the registrar: you answered.
Parameters 1
$queryarrayWhat is being asked: `sld`, `tld`, `module`. An empty `module` puts you on the WHOIS path, a filled one on the registrar path. Both pass through here.
Return 1
array|falseA filled array **takes over** the lookup: `status` (`available`, `unavailable` or `error`), with optional `message`, `premium`, `premium_price`. An empty array, `false` or no return lets the system carry on. With several listeners answering, the last one holds.
Listener PHP
```php
Hook::add('filter:domain.available', 10, function ($query) {
// Never ask the registrar about names on your block list.
if (Acme::blocked($query['sld'] ?? ''))
return ['status' => 'unavailable', 'message' => 'this name is not offered'];
return false; // let the system ask for the rest
});
```
#### Changing the collected result map
filterdomain.whois_result
`Registrar::check` passed by link
Runs once every extension has answered, right before the result goes back to the caller. You hold the whole map, not one extension.
Parameters 2
$resultarrayby linkDomain against result; each result carries `sld`, `tld`, `status`, and may carry `message`, `premium`, `premium_price`.
$contextarrayWhat was asked: `sld` and `tlds`.
Return 1
voidThe return is ignored; you write over the map. Overriding a premium price here is easier than catching each extension lookup.
Listener PHP
```php
Hook::add('filter:domain.whois_result', 10, function (&$result, $context) {
foreach ($result as $domain => $row) {
if (($row['premium'] ?? false) !== true) continue;
// Add your own margin to the premium price.
$result[$domain]['premium_price'] = round(((float) $row['premium_price']) * 1.15, 2);
}
});
```
#### Masking the raw record
filterdomain.whois_record
`ClientDomain::whois` passed by link personal data
Runs before the raw text from the registrar is shown to a visitor. That text holds somebody else's name, email and phone, so this is where masking belongs.
Parameters 2
$rawstringby linkThe full record text. It **arrives empty** when no record could be fetched, which is also where you can feed text from a source of your own.
$whoisContextarrayWhich name was asked for: `sld`, `tld`, `status`.
Return 1
voidThe return is ignored; you write over the text.
Listener PHP
```php
Hook::add('filter:domain.whois_record', 10, function (&$raw, $whoisContext) {
if ($raw === '') return;
// Hide the email and phone lines.
$raw = preg_replace('~^(.*(?:Email|Phone).*)$~mi', '[hidden]', $raw);
});
```
#### Following a document requirement change
actiondomain.doc_saved
`AdminProductsDomain` compliance record
Runs after the required document list of an extension changes. The change reaches backwards: orders already waiting on that extension may now need a different document.
Parameters 4
$tldstringThe extension, without a dot and in lower case.
$addedarrayNewly added document definitions.
$updatedarrayChanged definitions, id against data.
$removedarrayThe ids of definitions taken away.
Return 1
voidThe return is ignored. The record is already written.
Listener PHP
```php
Hook::add('action:domain.doc_saved', 10, function ($tld, $added, $updated, $removed) {
// A new document means waiting orders on that extension deserve a second look.
if ($added) Acme::reviewPendingOrders($tld);
});
```
### Pitfalls
> **The search filter runs AFTER sorting**
>
> The suggestions are sorted by state before you see them. A suggestion appended to the list stays **at the bottom**, where most customers never look. To put yours forward, place it at the **front**.
> **The extension format is strict**
>
> The featured list and the table rows want the extension **without a dot and in lower case**. Writing `.COM` breaks the match: the extension is found in no catalogue, no price resolves, and the screen quietly shows nothing.
> **Price hooks come after conversion**
>
> Both the renewal price and the table rows hand you a **converted** amount. Write your own price in that same currency; dropping the provider's cost in as-is shows the customer **a number from another currency**.
> **A category key has to match the extension rows**
>
> Adding a key to the category list opens **the button** and nothing else. That key also has to appear in the category list on the extension rows, or a customer pressing it sees **an empty list**.
### Related Articles
- [Domain Acquisition Hooks](https://dev.wisecp.com/en/domain-acquisition-hooks)
- Order Flow Hooks
- Domain Hooks
## Domain Forwarding Hooks
https://dev.wisecp.com/en/domain-forwarding-hooks
The eight hooks carrying an arriving visitor and post somewhere else, plus the add-on purchase opening those surfaces.
### Overview
Forwarding comes in two kinds and both sit behind **the same add-on**: one carries whoever arrives at the address, the other carries the post.
They differ in number. An address forward is **one** per domain, while mail forwarding is **a list**. That difference shows in the parameters: one carries a single record, the other source and target pairs.
### Reference
#### Stopping an address forward
gatedomain.url_forwarding_change
`ClientDomains` set and clear
Runs before the forward is set at the provider or cleared from it.
Parameters 3
$servicearrayThe domain service record.
$fwdarrayThe forward: `protocol` (`http`/`https`), `target` (the target without a scheme, trailing slash trimmed), `method` (`301`/`302`). On a clear it arrives as an **empty array**.
$verbstring`save` or `cancel`.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the provider is never called.
Listener PHP
```php
Hook::add('gate:domain.url_forwarding_change', 10,
function ($service, $fwd, $verb) {
if ($verb === 'cancel') return null; // leave a clear alone
// A permanent forward is cached by browsers; refuse an insecure target.
if (($fwd['protocol'] ?? '') !== 'https' && (int) ($fwd['method'] ?? 0) === 301)
return 'A permanent forward wants a secure address.';
return null;
});
```
#### Following an address forward
actiondomain.url_forwarding_changed
`ClientDomains` on success only
Runs after the forward was set at the provider or cleared from it.
Parameters 3
$servicearrayThe domain service record.
$fwdarrayThe forward that was set. On a clear it is an empty array, so do not read a target from it.
$verbstringThe action that ran.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.url_forwarding_changed', 10,
function ($service, $fwd, $verb) {
Audit::note('forwarding', $service['name'] ?? '',
$verb === 'cancel' ? 'cleared' : ($fwd['target'] ?? ''));
});
```
#### Changing the forward that was read
filterdomain.url_forwarding
`Hook::runRefs` by reference
Runs after the forward read from the provider was normalised, before it reaches the screen.
Parameters 2
$forwardingarrayrefA single record: `active`, `protocol`, `method`, `domain` (target without a scheme), `url` (the full address). `active` decides the screen's "is there a forward" state and `url` pre-fills the target box.
$servicearrayThe domain service record.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.url_forwarding', 10, function (&$forwarding, $service) {
// Keep active and url in step: never one filled with the other empty.
if (empty($forwarding['url'])) $forwarding['active'] = false;
});
```
#### Stopping a mail forward
gatedomain.email_forward_save
`ClientDomains` create and delete
Runs before a mail forwarding rule is created at the provider or deleted from it.
Parameters 4
$servicearrayThe domain service record.
$prefixstringThe local part on the domain. Only the part arrives, not the full address: `info` means `info@example.com`.
$targetstringThe target box. It can arrive empty on a delete.
$verbstring`create` or `delete`.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error and the provider is never called.
Listener PHP
```php
Hook::add('gate:domain.email_forward_save', 10,
function ($service, $prefix, $target, $verb) {
if ($verb === 'delete') return null;
// Forwarding the control boxes outward opens the door to a takeover.
if (in_array(strtolower($prefix), ['admin', 'postmaster', 'hostmaster'], true))
return 'That local part cannot be forwarded.';
return null;
});
```
#### Following a mail forward
actiondomain.email_forward_saved
`ClientDomains` on success only
Runs after the rule landed at the provider.
Parameters 4
$servicearrayThe domain service record.
$prefixstringThe source local part.
$targetstringThe target box.
$verbstringThe action that ran.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.email_forward_saved', 10,
function ($service, $prefix, $target, $verb) {
MailAudit::rule($verb, $prefix . '@' . ($service['name'] ?? ''), $target);
});
```
#### Changing the forwarding list
filterdomain.email_forwards
`Hook::runRefs` by reference
Runs after the rules read from the provider were normalised.
Parameters 2
$forwardsarrayrefThe rule list: every row carries `identity`, `prefix`, `source` (`prefix@domain`) and `target`. A delete sends those three back, so do not drop them.
$servicearrayThe domain service record.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.email_forwards', 10, function (&$forwards, $service) {
// KEEP identity, prefix and target: a delete targets the rule with them.
usort($forwards, fn ($a, $b) => strcmp($a['prefix'] ?? '', $b['prefix'] ?? ''));
});
```
#### Stopping an add-on purchase
gatedomain.addon_purchase
`ClientDomains` before the invoice
Runs before the customer buys the add-on, with **no record created yet**.
Parameters 2
$servicearrayThe domain service record.
$addonKeystringThe add-on being bought: `dns-manage`, `whois-privacy` or `forwarding`. The key uses **hyphens**; an underscore matches nothing.
Return 1
stringA non-empty string **stops** the purchase; it reaches the customer as the error and **no record is created**.
Listener PHP
```php
Hook::add('gate:domain.addon_purchase', 10, function ($service, $addonKey) {
// Selling a yearly add-on on a name about to expire is not right.
if (Acme::daysLeft($service) < 30)
return 'The domain is about to expire; renew it first.';
return null;
});
```
#### Following an add-on order
actiondomain.addon_ordered
`ClientDomains` the invoice is unpaid
Runs after the order was placed. The add-on is **waiting** here: it goes live once its invoice is paid.
Parameters 3
$servicearrayThe domain service record.
$addonKeystringThe add-on that was ordered.
$contextarrayThe order context: `invoice_id` (the **unpaid** invoice raised), `addon_id` (the waiting record), `addon_name`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.addon_ordered', 10,
function ($service, $addonKey, $context) {
// The add-on is NOT live yet: it opens once the invoice is paid.
Crm::pendingAddon((int) ($context['invoice_id'] ?? 0), $addonKey);
});
```
### Pitfalls
> **On a clear the forward arrives empty**
>
> While an address forward is being cleared, the hook hands you an **empty array** as the second parameter. A listener reaching for the old target finds nothing and quietly does the wrong thing. Where you need to know what was cleared, read it **at the gate** and keep it.
> **The mail hook hands you the local part**
>
> The source parameter is **the local part alone**, not a full address. You add the domain yourself, taking it from the service record. A listener expecting a full address matches **nothing**.
> **The order hook is not the moment the add-on opens**
>
> When an add-on order is placed the record is **waiting** and its invoice **unpaid**. Opening the surface here means handing over a service nobody paid for. The real opening happens on the payment side hooks.
> **The add-on key uses hyphens**
>
> The keys are `dns-manage`, `whois-privacy` and `forwarding`. Writing one with an underscore matches silently nothing: your listener runs and your condition **never** holds.
### Related Articles
- [Domain DNS Hooks](https://dev.wisecp.com/en/domain-dns-hooks)
- Invoice and Payment Hooks
- Domain Hooks
## Domain Lifecycle End Hooks
https://dev.wisecp.com/en/domain-lifecycle-end-hooks
The eight hooks along an unpaid domain's road to the end: the grace period, redemption, the drop, and importing.
### Overview
A domain past its date does not vanish in **one step**. First comes the grace period, where the name still renews at the normal price. Then redemption: the name stops working and getting it back is **far more expensive**. Finally the drop, where the name opens to everyone.
Each of the three has its own hook and all of them run from a **scheduled task**. Nobody presses a button and no one is watching a screen.
### Reference
#### Catching the start of the grace period
actiondomain.grace_started
`cronjobs/DomainLifecycle` a scheduled task
Runs the moment the domain entered its grace period; the name still works and renews at the normal price.
Parameters 2
$service_idintThe id of the domain service.
$statearrayThe lifecycle state: `stage`, `days_past_due`, `days_in_stage`. This stage also carries `grace_days`, `grace_fee` and `grace_fee_active`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.grace_started', 10, function ($service_id, $state) {
// Reaching the customer at this stage is the cheapest way back.
Crm::nudge($service_id, 'domain-grace', (int) ($state['grace_days'] ?? 0));
});
```
#### Catching the start of redemption
actiondomain.redemption_started
`cronjobs/DomainLifecycle` the name stopped working
Runs where the grace period ended. The name has **stopped working** here and a redemption fee applies.
Parameters 2
$service_idintThe id of the domain service.
$statearrayThe lifecycle state: `stage`, `days_past_due`, `days_in_stage`. This stage carries `redemption_days`, `redemption_fee`, `amount_cid` and `can_restore`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.redemption_started', 10, function ($service_id, $state) {
// The fee and its currency arrive in the state; do not work them out.
if (!empty($state['can_restore']))
Crm::urgent($service_id, (float) ($state['redemption_fee'] ?? 0),
(int) ($state['amount_cid'] ?? 0));
});
```
#### Stopping the drop request
gatedomain.delete_request
`cronjobs/DomainPurge` in a cron context
Runs before the cancellation request reaches the provider. It sits inside a scheduled task, so stopping it means **nobody sees an error**.
Parameters 3
$servicearrayThe domain service about to be dropped.
$statearrayThe lifecycle state: `stage`, `days_past_due`, `days_in_stage`.
$modulestringThe provider module's name. It arrives empty where no module is assigned.
Return 1
stringA non-empty string **stops** the drop. The task tries again next round, so keep your own mark for a lasting hold.
Listener PHP
```php
Hook::add('gate:domain.delete_request', 10, function ($service, $state, $module) {
// Hold the drop a round where the customer promised to pay.
if (Acme::promiseToPay((int) ($service['id'] ?? 0)))
return 'A payment was promised; the drop was held.';
return null;
});
```
#### Following the drop request
actiondomain.delete_requested
`cronjobs/DomainPurge` it reached the provider
Runs after the cancellation request was sent to the provider.
Parameters 3
$servicearrayThe domain service being dropped.
$statearrayThe lifecycle state: `stage`, `days_past_due`, `days_in_stage`.
$modulestringThe provider module's name; it can be empty.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.delete_requested', 10,
function ($service, $state, $module) {
Audit::note('domain-drop', $service['name'] ?? '', $module ?: 'no module');
});
```
#### Catching the finished drop
actiondomain.purged
`cronjobs/DomainPurge` no way back
Runs after the service was cancelled and the domain dropped. This is the **last step**.
Parameters 3
$service_idintThe id of the domain service.
$statearrayThe lifecycle state: `stage`, `days_past_due`, `days_in_stage`. At this point `stage` is the drop stage.
$modulestringThe provider module's name; it can be empty.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.purged', 10, function ($service_id, $state, $module) {
// The name is no longer ours: clear what hangs off it.
DnsMonitor::forget($service_id);
});
```
#### Following an expiry notice
actiondomain.expired_notice_sent
`cronjobs/DomainExpired` once per milestone
Runs after a notice was sent for a domain past its date.
Parameters 2
$service_idintThe id of the domain service.
$delayed_dayintThe days past the date. It is the notice milestone: the hook runs **more than once** for one name, with different day values.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.expired_notice_sent', 10,
function ($service_id, $delayed_day) {
// It runs per milestone: day 1, day 7 and day 15 arrive separately.
if ($delayed_day >= 15) Ops::escalate('domain-expiry', $service_id);
});
```
#### Following an import
actiondomain.imported
`Imports` a bulk job
Runs after domains were imported from a provider. The hook runs **once for the whole batch**, not per name.
Parameters 2
$importedarrayThe imported service labels: strings shaped like `"example.com (#123)"`. Labels arrive, **not** service records, so the id wants picking out of the text.
$module_namestringThe provider module the import ran against.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.imported', 10, function ($imported, $module_name) {
// Runs ONCE for the whole batch, not per name.
Ops::note('domain-import', $module_name . ': ' . count($imported));
});
```
#### Changing the grace and redemption fee
filterdomain.grace_redemption_save
`AdminProductsDomain` passed by link
Runs before a grace or redemption fee is saved. This is how you hold one fee policy in one place instead of typing it extension by extension.
Parameters 3
$set_dataarrayby linkThe price record about to be written: `amount`, `cid` (currency), `owner_id`, `status` and the rest.
$typestring`grace` or `redemption`.
$idintThe extension id. **A zero** means the record is not for one extension but the default for all of them.
Return 1
voidThe return is ignored; you write over the record. The hook fires once per currency and per type, so expect several calls for a single save.
Listener PHP
```php
Hook::add('filter:domain.grace_redemption_save', 10, function (&$set_data, $type, $id) {
// Make the grace period free on every extension.
if ($type === 'grace') $set_data['amount'] = 0;
});
```
### Pitfalls
> **No screen is watching these hooks**
>
> Every hook here runs from a scheduled task. Stopping a gate means **nobody sees an error**: not the customer, not the operator. Record your decision on your own side, or no one can tell why the domain never dropped.
> **Stopping is not permanent**
>
> The task **tries again** next round. Thinking "I stopped it once" at the gate is wrong; your condition is asked afresh every round. For a lasting hold, keep your own mark and read it at the gate.
> **The notice hook repeats for one name**
>
> Expiry notices go out milestone by milestone and the hook runs **again at each**. A listener reacting without reading the day value produces a run of alerts for a single name.
> **The import hands you labels, not records**
>
> The import hook hands you **strings** shaped like `"example.com (#123)"`. Expecting service records is wrong; where you need an id, pick it out of the text and read the record yourself.
### Related Articles
- [Domain Acquisition Hooks](https://dev.wisecp.com/en/domain-acquisition-hooks)
- Scheduled Task Hooks
- Domain Hooks
## Domain Verification Hooks
https://dev.wisecp.com/en/domain-verification-hooks
The nine hooks over registrant verification and reading from the provider — even a read has a gate of its own.
### Overview
Some extensions ask the registrant to prove who they are **with a document**. An unverified name can be suspended, so that flow has hooks of its own: a gate stopping the submission, an event reporting the outcome, and a filter handing you the whole screen.
The second group is less known: **read gates**. Reading name servers or contact details means a real request to the provider, so a gate stands in front of a read as well.
### Reference
#### Stopping a verification submission
gatedomain.verification_submit
`ClientDomains` before any file is handled
Runs before the submitted documents are handled and **nothing is saved yet**.
Parameters 3
$servicearrayThe domain service record.
$defsarrayThe field definitions the extension asks for: each with `key`, `type`, `name`, `required`, `options`. They differ by extension and module.
$tldstringThe name's extension.
Return 1
stringA non-empty string **stops** the submission; no file is handled and no field is written.
Listener PHP
```php
Hook::add('gate:domain.verification_submit', 10, function ($service, $defs, $tld) {
// A second submission while a review is open only causes confusion.
if (Acme::reviewOpen((int) ($service['id'] ?? 0)))
return 'Your earlier submission is still under review.';
return null;
});
```
#### Following a verification submission
actiondomain.verification_submitted
`ClientDomains` how many fields landed
Runs after the documents were handled and the fields saved.
Parameters 3
$servicearrayThe domain service record.
$submittedintHow many fields were saved. It can be zero, meaning a submission happened and no field landed.
$defsarrayThe extension's field definitions.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.verification_submitted', 10,
function ($service, $submitted, $defs) {
// Zero fields means the submission was empty: keep it out of the queue.
if ($submitted > 0) Ops::queue('registrant-review', $service['id'] ?? 0);
});
```
#### Changing the verification screen
filterdomain.verification_state
`Hook::runRefs` keep all three keys
Runs after the verification screen's whole payload was built, before it appears.
Parameters 2
$dataarrayrefThe screen payload: `state` (`none`, `form`, `review`, `rejected`, `verified`), `fields`, `operator_note`. `state` picks which shell is shown; leave all three keys in place.
$servicearrayThe domain service record.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.verification_state', 10, function (&$data, $service) {
// Leave state, fields and operator_note in place; the shell follows state.
if (($data['state'] ?? '') === 'rejected')
$data['operator_note'] = Acme::helpText($data['operator_note'] ?? '');
});
```
#### Stopping a contact read
gatedomain.contacts_get
`AdminServices` a read
Runs before the contact details are read from the provider.
Parameters 2
$servicearrayThe domain service record.
$serviceIdintThe service id.
Return 1
stringA non-empty string **stops** the read; the text is thrown as the error and the provider is never reached.
Listener PHP
```php
Hook::add('gate:domain.contacts_get', 10, function ($service, $serviceId) {
// Where the provider charges per query, hold the reads down.
if (Acme::readQuotaSpent($serviceId)) return 'Today\'s query allowance is spent.';
return null;
});
```
#### Following contact details that were read
actiondomain.contacts_fetched
`AdminServices` straight from the provider
Runs after the contact details came back from the provider.
Parameters 2
$servicearrayThe domain service record.
$whoisarrayThe contact data read from the provider.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.contacts_fetched', 10, function ($service, $whois) {
// Personal data: do not log it, only check it against our mirror.
Acme::compareMirror((int) ($service['id'] ?? 0), $whois);
});
```
#### Stopping a name server read
gatedomain.nameservers_get
`AdminServices` a read
Runs before the name servers are read from the provider.
Parameters 2
$servicearrayThe domain service record.
$serviceIdintThe service id.
Return 1
stringA non-empty string **stops** the read; the text is thrown as the error and the provider is never reached.
Listener PHP
```php
Hook::add('gate:domain.nameservers_get', 10, function ($service, $serviceId) {
if (($service['status'] ?? '') === 'transfer')
return 'Name servers cannot be read while a transfer runs.';
return null;
});
```
#### Following name servers that were read
actiondomain.nameservers_fetched
`AdminServices` a normalised list
Runs after the name servers came back from the provider.
Parameters 2
$servicearrayThe domain service record.
$nameserversarrayThe list that was read, normalised and ordered.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.nameservers_fetched', 10, function ($service, $nameservers) {
// A provider value different from ours means the two have drifted.
Acme::driftCheck((int) ($service['id'] ?? 0), $nameservers);
});
```
#### Stopping a DNS record read
gatedomain.dns_records_get
`AdminServices` a read
Runs before the DNS records are read from the provider.
Parameters 2
$servicearrayThe domain service record.
$serviceIdintThe service id.
Return 1
stringA non-empty string **stops** the read; the text is thrown as the error and the provider is never reached.
Listener PHP
```php
Hook::add('gate:domain.dns_records_get', 10, function ($service, $serviceId) {
// Without the DNS management add-on, reading makes no sense either.
if (!Acme::addonActive($serviceId, 'dns-manage')) return 'DNS management is off.';
return null;
});
```
### Pitfalls
> **A read gate leaves the screen empty**
>
> Stopping a read does more than cut the request: that part of the screen **never fills**, and the customer or operator may not see why. The text you return is shown to them, so say what was stopped and why **in that sentence**.
> **Contact data that was read is personal data**
>
> The contact read hook hands you names, addresses, phone numbers and e-mail. Do **not** put those in logs, outside systems or notification bodies. Where you need a comparison, keep **whether a difference exists** rather than the values.
> **The verification screen draws from three keys**
>
> `state` picks the shell, `fields` fills it, and `operator_note` carries the rejection reason. Dropping one breaks the screen: without `state`, for one, there is no telling which shell to draw.
> **Zero fields is still a submission**
>
> The verification event also runs where no field landed, with the counter at `0`. Assuming "a document arrived" without reading the number drops an empty submission into the review queue.
### Related Articles
- [Domain Contact Hooks](https://dev.wisecp.com/en/domain-contact-hooks)
- [Domain DNS Hooks](https://dev.wisecp.com/en/domain-dns-hooks)
- Domain Hooks
## Domain Profile Hooks
https://dev.wisecp.com/en/domain-profile-hooks
Saved contact profiles, default name servers and the renewal invoice — the last eight hooks of the domain area.
### Overview
Most hooks here belong to **an account** rather than to one domain. Contact profiles and default name servers are templates a customer fills once and uses on every name.
The last two sit on the money side: where a customer renews a domain by hand, a gate stands in front of the invoice and an event behind it.
### Reference
#### Following a profile delete
actiondomain.whois_profile_deleted
`ClientDomains` a last snapshot
Runs after a saved contact profile was deleted.
Parameters 3
$uidintThe account id. A sub-user's action is recorded against **the owner**.
$profileIdintThe id of the deleted profile.
$profilearrayThe profile **as it was before**: `id`, `name`, `information`, `detouse`. Take what you need from here; the record is gone.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.whois_profile_deleted', 10,
function ($uid, $profileId, $profile) {
// The record is gone: everything you need is in the third parameter.
Acme::dropProfileIndex($uid, $profileId);
});
```
#### Following the default profile
actiondomain.whois_profile_default_set
`ClientDomains` the record holds the OLD value
Runs after a profile was made the default.
Parameters 3
$uidintThe account id. A sub-user's action is recorded against **the owner**.
$profileIdintThe id of the profile made default.
$profilearrayThe profile record **from before the change**. Its default field still holds the **old** value, so do not read the new state from it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.whois_profile_default_set', 10,
function ($uid, $profileId, $profile) {
// The new default is the SECOND parameter; the third is the old record.
Acme::defaultProfile($uid, $profileId);
});
```
#### Changing the profile form
filterdomain.whois_profile_data
`Hook::runRefs` the key names are fixed
Runs before a saved profile is loaded into the form.
Parameters 3
$dataarrayrefThe fields going to the form: `id`, `name`, `first`, `last`, `org`, `email`, `phone`, `address`, `postal`, `city`, `country`. Keep the key names; the form fills by them.
$profilearrayThe raw database record. Fields the form leaves out (the state, a second address line) are **in here**.
$uidintThe account id. A sub-user's action is recorded against **the owner**.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.whois_profile_data', 10,
function (&$data, $profile, $uid) {
// A field the form leaves out sits in the raw record: take it from there.
$data['state'] = $profile['information']['State'] ?? '';
});
```
#### Following the default name servers
actiondomain.default_ns_saved
`ClientDomains` account-wide
Runs after the customer's default name server set was saved. The set belongs to the whole account, **not to one name**.
Parameters 2
$uidintThe account id. A sub-user's action is recorded against **the owner**.
$nsarrayThe saved set: the `ns1` … `ns4` keys, filled ones only. At least two are present.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.default_ns_saved', 10, function ($uid, $ns) {
// This set applies to EVERY new name on the account, not to one.
Acme::rememberDefaults($uid, $ns);
});
```
#### Following provider settings
actiondomain.registrar_settings_saved
`AdminProducts` an operator setting
Runs after a domain provider's settings were saved.
Parameters 2
$modulestringThe provider module whose settings were saved.
$settingsarrayThe saved settings. They can hold credentials; do not log them.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.registrar_settings_saved', 10, function ($module, $settings) {
// Record that they changed, never what is inside them.
Audit::note('registrar-settings', $module, 'updated');
});
```
#### Stopping a renewal invoice
gatedomain.renewal_invoice_create
`ClientDomains` before the invoice
Runs where a customer starts a manual renewal, before the invoice is raised. Stopping it means **no invoice and no line** is created.
Parameters 5
$servicearrayThe domain service being renewed.
$yearsintThe number of years chosen.
$subtotalfloatThe subtotal without tax. In the service's own currency.
$tldstringThe extension, **without a dot and lower case**.
$uidintThe account id.
Return 1
stringA non-empty string **stops** the invoice; the text reaches the customer as the error.
Listener PHP
```php
Hook::add('gate:domain.renewal_invoice_create', 10,
function ($service, $years, $subtotal, $tld, $uid) {
// Some extensions take no renewal longer than ten years.
if ($years > 10) return 'Renewals run to ten years at most.';
return null;
});
```
#### Following a renewal invoice
actiondomain.renewal_invoice_created
`ClientDomains` the invoice is unpaid
Runs after the renewal invoice was raised. The invoice is **unpaid** here and the domain is not renewed yet.
Parameters 5
$servicearrayThe domain service being renewed.
$yearsintThe number of years chosen.
$invoiceIdintThe id of the **unpaid** invoice.
$subtotalfloatThe subtotal without tax.
$duedateFullstringThe domain's **current** due date. Not the new one: the renewal lands after payment.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.renewal_invoice_created', 10,
function ($service, $years, $invoiceId, $subtotal, $duedateFull) {
// The domain is NOT renewed yet; that follows the payment.
Crm::pendingRenewal($invoiceId, $service['name'] ?? '', $years);
});
```
#### Following DNS records that were read
actiondomain.dns_records_fetched
`AdminServices` straight from the provider
Runs after the DNS records came back from the provider.
Parameters 2
$servicearrayThe domain service record.
$recordsarrayThe records that were read, normalised.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:domain.dns_records_fetched', 10, function ($service, $records) {
Acme::snapshotZone((int) ($service['id'] ?? 0), $records);
});
```
#### Following the detail page opening
actiondomain.detail.viewed
`website/domains` on every opening
Runs when a customer opens the management page of their own domain. Access checks are already behind you: the opener is confirmed as the owner.
Parameters 2
$servicearrayThe domain record: `id`, `name`, `owner_id`, `status`, `duedate` and the rest.
$serviceIdintThe id of the domain.
Return 1
voidThe return is ignored. It runs while the page opens, so whatever you do here is added to the customer's wait. Hand a slow call to the queue.
Listener PHP
```php
Hook::add('action:domain.detail.viewed', 10, function ($service, $serviceId) {
// Keep it light: the customer is waiting for the page.
Acme::touchLastSeen($serviceId);
});
```
### Pitfalls
> **The default-profile record holds the OLD state**
>
> On the default hook the third parameter is the profile record **from before the change**: its default field still holds the old value. Which profile is now the default is **the second parameter**. Reading the record and concluding "this one is not the default" comes from here.
> **These hooks belong to an account, not a domain**
>
> Profiles and default name servers are **account-wide** templates. The hooks hand you an account id rather than a service record, so a listener reaching for domain details finds nothing. A sub-user's action is recorded against **the owner**.
> **The date on the invoice is the old due date**
>
> The date field on the renewal invoice hook is the domain's **current** due date, not the one after renewing. The new date exists only once the **payment** lands. Using this one as "the new end" shows the customer the wrong day.
> **Provider settings carry credentials**
>
> The settings hook can hand you the **keys and passwords** used to reach the provider. Recording that they changed is fair; recording **what is in them** is not. Log which module was updated and nothing more.
### Related Articles
- [Domain Contact Hooks](https://dev.wisecp.com/en/domain-contact-hooks)
- Invoice and Payment Hooks
- Domain Hooks
## Domain Capability Hooks
https://dev.wisecp.com/en/domain-capability-hooks
The two hooks that hand a single domain capability to a provider other than the registrar.
### Overview
A domain service resolves to exactly one module: its registrar. So a provider that is not the registrar has no slot of its own. A DNS server, a forwarding service, a WHOIS privacy provider: none of them can register a domain, and none of them can be the module.
These two hooks open that door. One decides **what the screens offer**, the other decides **who answers the call**. The registrar keeps every capability you do not claim.
The capability names are shared: `nameservers`, `child_ns`, `transfer_lock`, `auth_code`, `dns_records`, `dns_edit`, `dnssec`, `email_forwarding`, `domain_forwarding`, `whois`, `whois_privacy`.
**Use both.** Only the matrix gives you a tab with nothing behind it. Only the provider gives you a capability nobody can reach.
### Reference
#### Opening a capability
filterdomain.capabilities
`Hook::runRefs` by reference from four screens
Runs once the module probe is done and before the tabs are built. Four screens compute this matrix separately and every one of them calls the hook: the customer panel, the customer API, the management panel and the admin API.
Parameters 2
$capsarrayrefThe capability matrix, `name => bool`. Raw names on all four screens; the admin payload renames them to `has_*` afterwards.
$contextarrayref`service` the domain record, `instance` the registrar or `null`, `surface` one of `website`, `client_api`, `admin_panel`, `admin_api`.
Return 1
voidThe matrix changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.capabilities', 10, function (&$caps, $context = []) {
$service = $context['service'] ?? [];
if (!MyDns::handles((int) ($service['id'] ?? 0))) return;
$caps['dns_records'] = true;
$caps['dns_edit'] = true;
});
```
#### Answering the call
filterdomain.capability_provider
`Services::instance_module()` by reference
Runs when a screen asks for the module instance and names the capability it is about to use. A plain lookup never reaches this hook, so the service lifecycle is untouched.
Parameters 2
$providerobject|falserefArrives as `false`. Assign an object and the call goes to it; anything else is ignored.
$contextarrayref`service` the domain record, `capability` the name being asked for, `instance` the registrar or `null`.
Return 1
voidThe provider is handed over **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:domain.capability_provider', 10, function (&$provider, $context = []) {
if (!in_array((string) ($context['capability'] ?? ''), ['dns_records', 'dns_edit'], true)) return;
$service = $context['service'] ?? [];
if (!MyDns::handles((int) ($service['id'] ?? 0))) return;
$provider = new MyDnsProvider($service);
});
```
#### What the provider must look like
Your provider carries the same method names the registrar would. Declare them as real methods.
Provider PHP
```php
class MyDnsProvider
{
public string $error = '';
public function set_service(int|array $service = []): void {}
public function get_dns_records(): array|false
{
// ... read the zone
return $records;
}
public function add_dns_record($type, $name, $value, $ttl, $priority): bool
{
// ... write one record
return true;
}
}
```
### Pitfalls
**A magic `__call()` will not work.** Every screen asks `method_exists()` before it calls anything, and a method served by `__call()` is invisible to that check. Your provider is then never called and nothing reports an error. Declare each method for real.
**One hook alone is not enough.** Open the matrix without a provider and the customer opens an empty tab. Hand over a provider without opening the matrix and the tab never shows up.
**Four screens, one answer.** The matrix is computed separately on each screen. A capability opened in the panel but missed in the API reads as the tab being visible while the endpoint refuses the request.
**The lifecycle is not yours.** A capability handover only covers the capability. Creation, renewal, transfer and cancellation keep going to the registrar, which is what keeps this safe.
### Related Articles
- [Domain DNS Hooks](https://dev.wisecp.com/en/domain-dns-hooks)
- [Domain Contact Hooks](https://dev.wisecp.com/en/domain-contact-hooks)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
# Hooks / Support Tickets
## Ticket Lifecycle Hooks
https://dev.wisecp.com/en/ticket-lifecycle-hooks
The eight hooks over creating, closing, transferring and locking a ticket.
### Overview
The path of a ticket lives here: it opens, its status moves, it is transferred, locked, and finally deleted or resolved on its own.
Two status hooks look alike but are separate: one reports a change made by staff, the other an automatic resolution **nobody touched**.
### Reference
#### Stopping a ticket opened by staff
gateticket.admin_create
`AdminTickets` before the write
Runs when staff open a ticket on behalf of a customer, before anything is written.
Parameters 3
$set_requestarrayThe ticket record to be written: title, status, department, priority and assignment.
$messagestringThe first message, with placeholders already resolved.
$udataarrayThe customer who will own the ticket.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.admin_create', 10, function ($set_request, $message, $udata) {
if (Acme::blacklisted((int) ($udata['id'] ?? 0))) return 'No ticket can be opened for this account.';
return null;
});
```
#### Following a ticket being created
actionticket.created
`AdminTickets` first message included
Runs after a ticket is created.
Parameters 1
$ticketarrayThe full ticket, **with the first message in it**: owner, title, status, department, priority and assignment.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.created', 10, function ($ticket) {
// The first message is not a separate parameter; it sits in the ticket.
Acme::classify((int) ($ticket['id'] ?? 0), $ticket['message'] ?? '');
});
```
#### Following a status change
actionticket.status_changed
`AdminTickets` five base states
Runs after the status of a ticket changes.
Parameters 4
$ticketarrayThe snapshot from **before** the change.
$old_statusstringThe previous base state: open, waiting, in progress, answered or solved.
$new_statusstringThe new base state.
$new_cstatusintThe new custom state. An operator may define their own states; a **zero** means none. A rule looking only at the base state never sees them.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.status_changed', 10,
function ($ticket, $old_status, $new_status, $new_cstatus) {
// Custom states are a second axis beside the base state.
if ($new_status === 'solved') Acme::stopSlaClock((int) ($ticket['id'] ?? 0));
});
```
#### Following an automatic resolution
actionticket.auto_resolved
`cronjobs` with nobody touching it
Runs when a ticket left without a reply closes itself. **Nobody closed it**: silence did.
Parameters 3
$ticket_idintThe id of the resolved ticket.
$ticketarrayThe current row, its status already written as solved.
$delayed_dayintHow many days passed since the last reply.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.auto_resolved', 10, function ($ticket_id, $ticket, $delayed_day) {
// Nobody closed it: silence did.
Acme::surveyLater($ticket_id, $delayed_day);
});
```
#### Following staff opening a ticket
actionticket.viewed
`AdminTickets` already marked read
Runs when staff open a ticket.
Parameters 2
$ticketarrayThe loaded ticket. The unread mark is **already cleared**: you cannot answer "was it new" from here.
$idintThe ticket id.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.viewed', 10, function ($ticket, $id) {
// The unread mark is already cleared.
Acme::trackHandling($id);
});
```
#### Following a ticket being transferred
actionticket.transferred
`AdminTickets` owner change
Runs after a ticket is transferred to another customer.
Parameters 3
$ticketIdintThe id of the transferred ticket.
$fromUserIdintThe previous owner.
$toUserIdintThe new owner. Its history moves with it: a conversation the previous owner can no longer see now sits with the new one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.transferred', 10, function ($ticketId, $fromUserId, $toUserId) {
// The history moved with it.
Acme::reindexOwner($ticketId, $toUserId);
});
```
#### Following a lock change
actionticket.lock_changed
`AdminTickets` replies close
Runs when a ticket is locked or unlocked. A customer **cannot reply** to a locked ticket.
Parameters 2
$ticketarrayThe record before the change.
$lockedintThe new lock state: one for locked, zero for open.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.lock_changed', 10, function ($ticket, $locked) {
// A customer cannot reply to a locked ticket.
if ($locked === 1) Acme::notifyLocked((int) ($ticket['user_id'] ?? 0));
});
```
#### Following a ticket being deleted
actionticket.deleted
`AdminTickets` the id only
Runs after a ticket is deleted.
Parameters 1
$ticket_idintThe id of the deleted ticket. No record is passed: if you need its content you must have kept it **before** the deletion.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.deleted', 10, function ($ticket_id) {
// No record is passed: keep the content beforehand if you need it.
Acme::dropFromIndex('ticket', $ticket_id);
});
```
### Pitfalls
> **In the view hook the unread mark is already cleared**
>
> The hook runs when staff open a ticket, but the unread flag is cleared **before** it. You cannot answer "was this new" from here; track the first opening separately.
> **The delete hook carries only the id**
>
> Unlike other deletion hooks **no ticket record is passed**. If you need its title, owner or content you must have kept it beforehand; by the time the hook runs there is nowhere left to read it from.
### Related Articles
- Support Ticket Hooks
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Customer-side Ticket Hooks
https://dev.wisecp.com/en/client-ticket-hooks
The eight hooks over what a customer does: opening, replying, closing and rating.
### Overview
Everything a customer can do on the support side lives here: opening a ticket, replying, closing, reopening and rating.
The difficulty of this branch is the question **who did it**. A sub-user may act on somebody else’s account and a guest may belong to no account at all, so the hooks carry the account and the login separately.
### Reference
#### Following a customer opening a ticket
actionticket.opened_by_client
`ClientTickets` zero for a guest
Runs when a ticket is opened by a customer or through email.
Parameters 4
$ticketAfterarrayThe freshly created ticket.
$messagestringThe first message with its normalised body.
$clientIdintThe owner. It is **zero** for an **unrecognised sender** arriving by email: do not use it without looking the account up.
$replyIdintThe id of the first reply row.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.opened_by_client', 10,
function ($ticketAfter, $message, $clientId, $replyId) {
// It arrives as ZERO for an unrecognised sender.
if (!$clientId) { Acme::queueIdentify($ticketAfter); return; }
Acme::classify((int) ($ticketAfter['id'] ?? 0), $message);
});
```
#### Stopping a customer reply
gateticket.reply_by_client
`ClientTickets` shape varies by source
Runs before a customer replies to a ticket. Replies from the panel, from email and from a guest link all pass here.
Parameters 5
$ticketarrayThe ticket being replied to. ? **Its shape varies by source**: what arrives from the panel and what arrives by email do not carry the same fields. Test a field before reaching for it.
$messagestringThe text to be sent, as plain text.
$ownerIdintThe account that owns the ticket. **Zero for a guest.**
$loginIdintThe login doing it. It **differs** from the owner when a sub-user replies on another account; zero for a guest.
$isGuestboolWhether it came through a guest link.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.reply_by_client', 10,
function ($ticket, $message, $ownerId, $loginId, $isGuest) {
// For a guest both ids arrive as ZERO.
if ($isGuest && Acme::guestRepliesClosed()) return 'Guest replies are closed.';
return null;
});
```
#### Following a customer reply
actionticket.reply_added_by_client
`ClientTickets` zero for a guest
Runs after a customer replies to a ticket.
Parameters 4
$ticketAfterarrayThe fresh ticket after the reply.
$messagestringThe message added.
$clientIdintWho wrote it; it can be zero on an anonymous email reply.
$replyIdintThe id of the reply added.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.reply_added_by_client', 10,
function ($ticketAfter, $message, $clientId, $replyId) {
Acme::restartSlaClock((int) ($ticketAfter['id'] ?? 0));
});
```
#### Following a customer closing a ticket
actionticket.closed_by_client
`ClientTickets` two separate ids
Runs when a customer closes their own ticket.
Parameters 3
$ticketarrayThe snapshot from **before** closing.
$ownerIdintThe account the ticket belongs to.
$loginIdintThe identity that **actually did it**. When a sub-user closes another account’s ticket the two differ: this is the one that belongs in an audit record.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.closed_by_client', 10, function ($ticket, $ownerId, $loginId) {
// The LOGIN id is the one that belongs in the audit.
Acme::audit('ticket-closed', $loginId, $ownerId);
});
```
#### Following a customer reopening a ticket
actionticket.reopened_by_client
`ClientTickets` two separate ids
Runs when a customer reopens a closed ticket.
Parameters 3
$ticketarrayThe snapshot from **before** reopening.
$ownerIdintThe account the ticket belongs to.
$loginIdintThe login that did it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.reopened_by_client', 10, function ($ticket, $ownerId, $loginId) {
Acme::restartSlaClock((int) ($ticket['id'] ?? 0));
});
```
#### Following a rating
actionticket.rated
`ClientTickets` two scopes
Runs when a customer rates a ticket or a single staff reply. **Two separate scopes** land on the same hook.
Parameters 5
$scopestringWhat was rated: `ticket` or `reply`. Check this first: the two scopes fill their parameters differently.
$ratingintThe score, one to five. A value outside that range **never reaches** the hook.
$ticketIdintThe ticket id; **filled in both scopes**.
$replyIdintThe reply rated. It is **zero** in the ticket scope.
$ownerIdintThe account the ticket belongs to.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.rated', 10,
function ($scope, $rating, $ticketId, $replyId, $ownerId) {
// Check the scope first: the reply id is ZERO in the ticket scope.
if ($scope === 'reply') { Acme::scoreAgent($replyId, $rating); return; }
Acme::scoreTicket($ticketId, $rating);
});
```
#### Following a guest viewing
actionticket.guest.viewed
`ClientTickets` carries the access value
Runs when somebody not signed in views a ticket through a link.
Parameters 2
$ticketarrayThe resolved ticket. ? It holds the **sender’s name, email and access value**. Whoever sees that value can open the ticket: keep it out of your records and logs.
$tokenstringThe access value from the address, already verified.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.guest.viewed', 10, function ($ticket, $token) {
// Write the access value NOWHERE.
Acme::countGuestView((int) ($ticket['id'] ?? 0));
});
```
#### Changing a customer message
filterticket.client_message
`ClientTickets` passed by link
Runs before the text a customer wrote is saved. New tickets and replies both pass here.
Parameters 2
$messagestringby linkThe message body, as plain text.
$ctxarrayContext: the source, the ticket id, the account and whether it is a guest. On a new ticket the id is **zero**: the ticket does not exist yet.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.client_message', 10, function (&$message, $ctx) {
// On a new ticket the ticket id is ZERO.
$message = Acme::stripSecrets($message);
});
```
### Pitfalls
> **The account and the login are not the same thing**
>
> The closing, reopening and reply hooks carry two ids: the **account the ticket belongs to** and the login that **actually did it**. When a sub-user works on somebody else’s account they differ. The login belongs in the audit record; the permission decision follows the account.
> **The guest view hook carries the access value**
>
> The ticket data holds the sender’s name, email and **access value**. Whoever sees that value can open the ticket: writing it into your records, your logs or an outside service copies the link to a third place.
### Related Articles
- Support Ticket Hooks
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Staff Reply Hooks
https://dev.wisecp.com/en/staff-reply-hooks
The eight hooks over staff replies, internal notes and assignment.
### Overview
Every point where staff touch a ticket lives here: writing a reply, editing it, deleting it, adding an internal note and assigning.
There are three reply hooks and they should not be confused: the one staff write, the one a customer writes and the one a **scheduled task** writes. The last carries its parameters in a single array.
### Reference
#### Stopping a staff reply
gateticket.reply
`AdminTickets` signature attached
Runs before a staff reply is sent.
Parameters 3
$ticketarrayThe ticket being replied to.
$messagestringThe final text. It carries markup and the **signature is already attached**: allow for that if you measure length.
$admin_idintThe staff member writing it.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.reply', 10, function ($ticket, $message, $admin_id) {
// The signature is already in: allow for it when measuring length.
if (Acme::containsSecret($message)) return 'The reply holds a value that must not be shared.';
return null;
});
```
#### Following a staff reply
actionticket.reply_added
`AdminTickets` hydrated reply
Runs after a staff reply is added.
Parameters 3
$ticketarrayThe fresh ticket after the reply.
$reply_idintThe id of the reply added.
$replyarrayThe whole reply: its text, author, attachments and address.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.reply_added', 10, function ($ticket, $reply_id, $reply) {
Acme::stopSlaClock((int) ($ticket['id'] ?? 0));
});
```
#### Following an automatic reply
actionticket.replied
`cronjobs` one context array
Runs when a scheduled task adds a reply to a ticket. Unlike its siblings the parameters arrive in **a single array**.
Parameters 1
$contextarrayEverything is here: the source, the current ticket and the reply added. Expect no separate parameters; this hook carries one array.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.replied', 10, function ($context) {
// One array: different from its siblings.
$ticket = $context['request'] ?? [];
Acme::noteAutoReply((int) ($ticket['id'] ?? 0));
});
```
#### Following a reply being edited
actionticket.reply_updated
`AdminTickets` after the edit
Runs after a reply is edited.
Parameters 3
$ticketIdintThe ticket id.
$replyIdintThe id of the edited reply.
$replyarrayThe updated reply. The previous version is not passed: to compare, you must have kept a copy yourself.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.reply_updated', 10, function ($ticketId, $replyId, $reply) {
// The previous version is not passed.
Acme::reindexReply($replyId, $reply['message'] ?? '');
});
```
#### Following a reply being deleted
actionticket.reply_deleted
`AdminTickets` after deletion
Runs after a reply is deleted.
Parameters 3
$ticketIdintThe ticket id.
$replyIdintThe id of the deleted reply.
$replyarrayThe deleted reply record: its owner and whether it was from staff.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.reply_deleted', 10, function ($ticketId, $replyId, $reply) {
Acme::dropFromIndex('reply', $replyId);
});
```
#### Stopping an internal note
gateticket.note_add
`AdminTickets` the customer never sees it
Runs before staff add an internal note. Notes are **never shown to the customer**.
Parameters 3
$ticketarrayThe ticket the note goes on.
$messagestringThe note content.
$admin_idintThe staff member adding it.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.note_add', 10, function ($ticket, $message, $admin_id) {
if (Acme::tooLong($message)) return 'The note is too long.';
return null;
});
```
#### Following an internal note
actionticket.note_added
`AdminTickets` the note may be empty
Runs after an internal note is added.
Parameters 3
$ticketarrayThe ticket the note went on.
$admin_idintThe staff member who added it.
$notearrayThe note data: its text, whether it is pinned, and attachments. ? It **can arrive empty** when the note could not be read. Test before reaching into it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.note_added', 10, function ($ticket, $admin_id, $note) {
// The note CAN be empty.
if (!$note) return;
Acme::mirrorNote((int) ($ticket['id'] ?? 0), $note['message'] ?? '');
});
```
#### Following an assignment
actionticket.assigned
`AdminTickets` zero means unassigned
Runs when a ticket is assigned to staff or unassigned.
Parameters 3
$ticketarrayThe ticket **before** the assignment.
$old_assigned_idintThe previous assignee; a **zero** means none.
$new_assigned_idintThe new assignee; a **zero** means it was unassigned.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.assigned', 10,
function ($ticket, $old_assigned_id, $new_assigned_id) {
// Zero means it was unassigned.
if (!$new_assigned_id) { Acme::backToPool((int) ($ticket['id'] ?? 0)); return; }
Acme::notifyAgent($new_assigned_id, (int) ($ticket['id'] ?? 0));
});
```
### Pitfalls
> **The note data can be empty**
>
> The third parameter of the internal note hook is **empty** when the note could not be read. A listener reaching straight into it fails there; test on the first line.
> **The automatic reply hook carries one array**
>
> Its siblings give the ticket, the reply id and the reply as separate parameters; the scheduled-task reply carries all of it in **a single context array**. A listener expecting the same signature works with empty values here.
### Related Articles
- Support Ticket Hooks
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Ticket Organisation Hooks
https://dev.wisecp.com/en/ticket-organisation-hooks
The seven hooks over merging, splitting and moving tickets.
### Overview
The operations that reorganise tickets live here: merging, splitting, and changing the department, priority or linked service.
The first two cannot be undone. A merge **deletes** everything but the target; a split moves replies into a new ticket. That is what makes the gates valuable.
### Reference
#### Stopping a ticket merge
gateticket.merge
`AdminTickets` the others are deleted
Runs before tickets are merged. A merge cannot be undone: **everything but the target is deleted**.
Parameters 2
$primary_idintThe target ticket; the others move into it.
$merge_idsarrayThe other tickets; the target is not in this list.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.merge', 10, function ($primary_id, $merge_ids) {
// Everything but the target is DELETED: this cannot be undone.
foreach ($merge_ids as $id)
if (Acme::underLegalHold((int) $id)) return 'A ticket under legal hold cannot be merged.';
return null;
});
```
#### Following a merge
actionticket.merged
`AdminTickets` after the merge
Runs after the tickets are merged.
Parameters 2
$primary_idintThe target ticket.
$merged_idsarrayThe ids merged in and **deleted**. Those ids no longer exist: point them at the target in your own records.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.merged', 10, function ($primary_id, $merged_ids) {
// Those ids are gone: point them at the target.
foreach ($merged_ids as $id) Acme::redirectRef((int) $id, $primary_id);
});
```
#### Stopping a ticket split
gateticket.split
`AdminTickets` an unverified list
Runs before some replies of a ticket are moved into a new one.
Parameters 2
$sourcearrayThe source ticket being split.
$reply_idsarrayThe ids of the replies to move. They are cleaned but **not yet checked against the database**: an id here may not really belong to that ticket.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.split', 10, function ($source, $reply_ids) {
// The list has not been checked against the database yet.
if (count($reply_ids) > 50) return 'At most 50 replies can move at once.';
return null;
});
```
#### Following a split
actionticket.split
`AdminTickets` a verified list
Runs after the new ticket is created and the replies have moved.
Parameters 3
$sourcearrayThe source ticket.
$new_ticketarrayThe newly created ticket.
$moved_reply_idsarrayThe ids that actually moved. Unlike in the gate this list is **verified**: anything asked for but not moved is absent.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.split', 10, function ($source, $new_ticket, $moved_reply_ids) {
// This list is verified: what really moved.
Acme::reindexSplit((int) ($new_ticket['id'] ?? 0), $moved_reply_ids);
});
```
#### Following a department change
actionticket.department_changed
`AdminTickets` zero means none
Runs after a ticket moves to another department. The department decides who sees the ticket.
Parameters 3
$ticketarrayThe record before the change.
$oldDepartmentIdintThe previous department; a zero means none.
$newDepartmentIdintThe new department.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.department_changed', 10,
function ($ticket, $oldDepartmentId, $newDepartmentId) {
// The department decides who sees it.
Acme::notifyDepartment($newDepartmentId, (int) ($ticket['id'] ?? 0));
});
```
#### Following a priority change
actionticket.priority_changed
`AdminTickets` four levels
Runs after the priority of a ticket changes.
Parameters 3
$ticketarrayThe record before the change.
$oldPriorityintThe previous level.
$newPriorityintThe new level.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.priority_changed', 10,
function ($ticket, $oldPriority, $newPriority) {
if ($newPriority > $oldPriority) Acme::escalate((int) ($ticket['id'] ?? 0));
});
```
#### Following the linked service changing
actionticket.service_changed
`AdminTickets` zero means unlinked
Runs after the service a ticket is linked to changes.
Parameters 3
$ticketarrayThe record before the change.
$oldServiceIdintThe previous service; a zero means it was not linked.
$newServiceIdintThe new service; a **zero means the link was removed**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.service_changed', 10,
function ($ticket, $oldServiceId, $newServiceId) {
// Zero means the link was removed.
if (!$newServiceId) return;
Acme::attachServiceContext((int) ($ticket['id'] ?? 0), $newServiceId);
});
```
### Pitfalls
> **A merge deletes the other tickets**
>
> In a merge everything but the target is **deleted**, not merely moved. The ids in the event hook are records that no longer exist: point them at the target on your side, or you are left with broken references.
> **The list in the split gate is not verified yet**
>
> The reply ids reaching the gate are cleaned but **not matched against the database**: the list may hold an id that does not belong to that ticket. To see what really moved, read the list in the event hook.
### Related Articles
- Support Ticket Hooks
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Ticket View Hooks
https://dev.wisecp.com/en/ticket-view-hooks
The nine hooks over the lists, the conversation and the pickers on screen.
### Overview
Everything visible on screen passes through these hooks: the lists, the conversation thread, the department and service pickers, the data of the detail page.
One works differently from the rest: the list query hands you not ready rows but **the query itself**, and it is called twice for one listing.
### Reference
#### Changing the department list
filterticket.departments
`ClientTickets` passed by link
Runs once the department list shown to a customer is built. Hiding a department also stops tickets being opened there.
Parameters 2
$departmentsarrayby linkThe visible departments.
$langstringThe active language.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.departments', 10, function (&$departments, $lang) {
// Hiding one also stops tickets being opened there.
$departments = array_values(array_filter($departments,
fn ($d) => Acme::departmentOpen((int) ($d['id'] ?? 0))));
});
```
#### Changing the priority options
filterticket.priorities
`ClientTickets` selected flag included
Runs once the priorities a customer may pick are prepared.
Parameters 1
$prioritiesarrayby linkThe options, each carrying a value, a label and whether it is selected. Drop the selected one and the form is left with nothing marked.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.priorities', 10, function (&$priorities) {
// Drop the selected one and nothing stays marked on the form.
$priorities = array_values(array_filter($priorities,
fn ($p) => (int) ($p['value'] ?? 0) < 4));
});
```
#### Changing the service picker
filterticket.related_services
`ClientTickets` grouped structure
Runs once the service picker shown while opening a ticket is prepared.
Parameters 2
$serviceGroupsarrayby linkThe grouped picker data; each group has a label and items. Do not flatten it: the template expects the group layer.
$uidintThe **active account** opening the ticket. Not the login: a sub-user may be listing another account’s services.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.related_services', 10, function (&$serviceGroups, $uid) {
// Do not flatten it: the template expects the group layer.
$serviceGroups[] = ['label' => 'Acme', 'items' => Acme::servicesFor($uid)];
});
```
#### Changing the conversation thread
filterticket.thread
`ClientTickets` newest first
Runs before the reply thread of a ticket reaches the screen.
Parameters 2
$threadarrayby linkThe reply rows, **newest first**. Each carries its author, date and whether it came from staff.
$ctxarrayContext: the ticket id, the login id and whether it is a guest. For a guest the login id is zero.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.thread', 10, function (&$thread, $ctx) {
// The order is newest first.
foreach ($thread as $i => $row)
if ($row['is_staff'] ?? false) $thread[$i]['author'] = Acme::displayName($row);
});
```
#### Changing the detail page data
filterticket.detail_data
`AdminTickets` all the page data
Runs once the ticket detail page is prepared. What you hold is **all** the data going to the template.
Parameters 2
$dataarrayby linkAll the page data. Take care not to overwrite existing keys: a value lost here leaves a blank area on the page.
$ticketarrayThe active ticket.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.detail_data', 10, function (&$data, $ticket) {
// Do not overwrite existing keys.
$data['acme_risk'] = Acme::riskScore((int) ($ticket['user_id'] ?? 0));
});
```
#### Narrowing the list query
filterticket.list_query
`AdminTickets` the query builder
Runs before the ticket list query is executed. What you hold is not ready rows but **the query itself**.
Parameters 3
$stmtobjectby linkThe query builder; you may chain conditions onto it.
$filtersarrayThe resolved filters: status, department, customer, assignment and priority.
$rCountboolWhether this is the **counting** query. ? The hook runs **twice** for one listing: once to count, once for the data. Add your condition to only one and the paging stops matching the rows.
Return 1
voidThe return is ignored; you chain the condition onto the builder.
Listener PHP
```php
Hook::add('filter:ticket.list_query', 10, function (&$stmt, $filters, $rCount) {
// The hook runs TWICE: to count and for the data. Add it to both.
$stmt->where('t.did', '!=', Acme::INTERNAL_DEPT);
});
```
#### Changing the list rows
filterticket.list_rows
`ClientTickets` per page
Runs before the customer ticket list reaches the screen.
Parameters 2
$rowsarrayby linkThe rows of that page: reference, subject, status, rating and department. Only the **page being viewed** arrives, not the whole list.
$uidintThe active account; the rows are already scoped to it.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.list_rows', 10, function (&$rows, $uid) {
// Only the page being viewed arrives.
foreach ($rows as $i => $r) $rows[$i]['subject'] = Acme::shorten($r['subject'] ?? '');
});
```
#### Narrowing a bulk action
filterticket.bulk_action_ids
`AdminTickets` narrowing only
Runs before a bulk action is applied. This is how you keep certain tickets out of it.
Parameters 2
$idsarrayby linkThe tickets to be handled. This list is for **narrowing**: remove entries. Adding one closes or deletes a ticket the administrator never picked.
$actionstringThe action applied: closing, deleting and their blocking variants.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.bulk_action_ids', 10, function (&$ids, $action) {
// It is for NARROWING: do not add.
$ids = array_values(array_filter($ids, fn ($id) => !Acme::underLegalHold((int) $id)));
});
```
#### Changing the access groups
filterticket.access_groups
`ClientTickets` passed by link
Runs once the access groups shown while opening a ticket are prepared.
Parameters 2
$groupsarrayby linkThe visible groups: id, name and icon.
$langstringThe active language of the page.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.access_groups', 10, function (&$groups, $lang) {
$groups = array_values(array_filter($groups,
fn ($g) => Acme::groupVisible((int) ($g['id'] ?? 0))));
});
```
### Pitfalls
> **The list query runs twice for one listing**
>
> The hook is called once for the **count** and once for the **data**. Add your condition to only one and the paging stops matching the real row count: the user sees empty pages. Unless you branch on the counting flag, add it to both.
> **The bulk list is for narrowing**
>
> Entries are **removed** through this filter. Adding one closes or deletes a ticket the administrator never picked, and the list they approved on screen parts ways with the list actually handled.
### Related Articles
- Support Ticket Hooks
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Ticket Field and Email Hooks
https://dev.wisecp.com/en/ticket-field-and-mail-hooks
The nine hooks over custom fields and tickets arriving by email.
### Overview
Two subjects meet here: the **custom fields** an operator defines, and the handling of tickets arriving by email.
The email gates stand apart from other gates: your block raises no error and is **skipped silently**. It stops the unwanted message but leaves no trace, so you must record the reason yourself.
### Reference
#### Stopping a custom field being saved
gateticket.custom_field.save
`AdminTickets` zero means new
Runs before a ticket custom field is saved.
Parameters 3
$idintThe id being edited; a **zero on a new record**.
$didintThe department it belongs to; a **zero** makes it show in every department.
$typestringThe field type: text, long text, password, select, radio or checkbox.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.custom_field.save', 10, function ($id, $did, $type) {
// A zero department means it shows everywhere.
if ($type === 'password' && $did === 0)
return 'A password field cannot be opened to every department.';
return null;
});
```
#### Following a custom field being saved
actionticket.custom_field.saved
`AdminTickets` language data separate
Runs after a custom field is saved.
Parameters 2
$fieldarrayThe **structural** record: id, department, status and rank. Its name and description are **not here**: they live in the language record and are read separately.
$isNewboolTrue when newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.custom_field.saved', 10, function ($field, $isNew) {
// Name and description live in the language record, not here.
Acme::syncFieldSchema((int) ($field['id'] ?? 0));
});
```
#### Stopping a custom field deletion
gateticket.custom_field.delete
`AdminTickets` always a list
Runs before custom fields are deleted.
Parameters 1
$idarrayThe ids to be deleted. A single deletion is still a **one-element array**: a check expecting a number catches nothing.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:ticket.custom_field.delete', 10, function ($id) {
// It is an array even for a single deletion.
foreach ($id as $one)
if (Acme::fieldHasData((int) $one)) return 'A field holding data cannot be deleted.';
return null;
});
```
#### Following a custom field being deleted
actionticket.custom_field.deleted
`AdminTickets` language record in hand
Runs after a custom field is deleted.
Parameters 2
$iintThe id of the deleted field.
$flangarrayIts language record as taken **before** the deletion: name, description and options. If you need its name, this is your only source.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:ticket.custom_field.deleted', 10, function ($i, $flang) {
// If you need the name, the language record is the only source.
Acme::dropFieldSchema($i, $flang['name'] ?? '');
});
```
#### Changing the custom field list
filterticket.custom_fields
`AdminTickets` passed by link
Runs after the custom fields are read. Add a field of your own to the list here.
Parameters 2
$fieldsarrayby linkThe field rows: id, department, name, type and options.
$ctxarrayby linkContext: language, department and status filter. A **zero** department means every department is being asked for.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.custom_fields', 10, function (&$fields, &$ctx) {
// A zero department means every department is being asked for.
$fields = array_values(array_filter($fields,
fn ($f) => Acme::fieldVisible((int) ($f['id'] ?? 0))));
});
```
#### Changing the group fields
filterticket.access_group_fields
`AdminTickets` the language is never empty
Runs after the custom fields tied to an access group are read.
Parameters 2
$fieldsarrayby linkThe group-scoped field rows.
$ctxarrayby linkContext: the language and the group id. Even when the call leaves it empty the language is filled in before the hook: it **never arrives empty**.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:ticket.access_group_fields', 10, function (&$fields, &$ctx) {
// The language never arrives empty.
$fields = Acme::orderFields($fields, $ctx['lang']);
});
```
#### Skipping an incoming email
gateticket.pipe_import
`cronjobs` a skip, not a failure
Runs before an incoming email becomes a ticket. This is where you keep unwanted mail out of the system entirely.
Parameters 3
$mailarrayThe raw email: subject, body, sender, recipient, attachments and address.
$didintThe department from the source; a **zero** means it will be resolved from the address.
$msgIdstringThe unique id of the message.
Return 1
string|null**A non-empty text skips the email entirely**. ? Unlike other gates **nothing is thrown**: the scheduled task records it as skipped and the mail job is **not counted as failed**. Your block is silent. Record the reason yourself.
Listener PHP
```php
Hook::add('gate:ticket.pipe_import', 10, function ($mail, $did, $msgId) {
// The veto is SILENT: record the reason yourself.
if (Acme::isAutoReply($mail)) {
Acme::log('auto-reply skipped', $msgId);
return 'auto-reply';
}
return null;
});
```
#### Stopping a ticket opening from email
gateticket.open
`cronjobs` a skip, not a failure
Runs immediately before an incoming email becomes a ticket. The message has passed the mail gate and its department is resolved.
Parameters 6
$subjectstringThe ticket title, normalised.
$messagestringThe first message body.
$departmentIdintThe resolved department.
$clientIdintThe customer id; **zero for an unrecognised sender**.
$clientEmailstringThe sender address.
$mailarrayThe raw email object.
Return 1
string|null**A non-empty text stops the ticket being opened**. Same shape as the mail gate: nothing is thrown, the job is recorded as skipped.
Listener PHP
```php
Hook::add('gate:ticket.open', 10,
function ($subject, $message, $departmentId, $clientId, $clientEmail, $mail) {
// For an unrecognised sender the customer id is ZERO.
if (!$clientId && Acme::strangersBlocked()) return 'unrecognised sender';
return null;
});
```
#### Cleaning the text from an email
filterticket.pipe_message_text
`cronjobs` both by link
Runs before the body and subject of an incoming email are written to a ticket. Trimming quoted blocks and signatures belongs here.
Parameters 3
$messagestringby linkThe normalised body.
$subjectstringby linkThe ticket subject; the reference tag is already stripped.
$mailarrayThe raw email object, there for context.
Return 1
voidThe return is ignored; **both** are passed by link and both may be changed.
Listener PHP
```php
Hook::add('filter:ticket.pipe_message_text', 10, function (&$message, &$subject, $mail) {
// Both are passed by link.
$message = Acme::stripQuotedReply($message);
});
```
### Pitfalls
> **The veto in the email gates is silent**
>
> When other gates block, an error is thrown and the user sees the reason. The email gates do not work that way: your block is recorded as **skipped**, the job is not counted as failed and nobody sees anything. It is the right place to stop unwanted mail, but without recording the reason yourself no trace remains.
> **The field name lives in the language record**
>
> The custom field save event gives the **structural** row: id, department, status, rank. The name and description are **not** there; they sit in the language record. A listener looking for the name works with an empty value.
### Related Articles
- Support Ticket Hooks
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
# Hooks / Products
## Product Lifecycle Hooks
https://dev.wisecp.com/en/product-lifecycle-hooks
The eight hooks over creating, updating, deleting and switching a product.
### Overview
A product travels three steps: it is created, updated and deleted. Each has a gate you can stop at in front of it and an event that reports it behind.
Two status hooks sit beside them. The single one fires per product; the bulk one fires **once** when an action reaches many products from the list.
### Reference
#### Stopping a product being created
gateproduct.create
`AdminProducts` before the write
Runs before a new product is created.
Parameters 2
$inputarrayThe form input: type, group, category, name, module and address.
$statearrayContext: the group keys, the default currency and the language keys.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.create', 10, function ($input, $state) {
if (!Acme::namingOk($input['name'] ?? '')) return 'The product name breaks the naming rule.';
return null;
});
```
#### Following a product being created
actionproduct.created
`AdminProducts` zero means it failed
Runs after a product is created.
Parameters 2
$new_idintThe id of the new product. ? **A zero means no product was created**. A listener that uses the id straight away then works on a record that is not there.
$inputarrayThe creation input: type, group, category, name, module and address.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.created', 10, function ($new_id, $input) {
// ZERO = no product was created.
if (!$new_id) return;
Acme::registerCatalogItem($new_id, $input['name'] ?? '');
});
```
#### Stopping a product update
gateproduct.update
`AdminProducts` before and after in hand
Runs before a product is updated. You hold both the new data and the old record, so you can compare what changed.
Parameters 3
$idintThe product id.
$inputarrayThe new data about to be written.
$detailarrayThe record as it was **before** the change.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.update', 10, function ($id, $input, $detail) {
// You hold both records: measure the difference.
if (($detail['module'] ?? '') !== ($input['module'] ?? '') && Acme::hasLiveServices($id))
return 'The module cannot change while live services run on it.';
return null;
});
```
#### Following a product update
actionproduct.updated
`AdminProducts` before and after in hand
Runs after the product is updated.
Parameters 3
$idintThe product id.
$inputarrayThe full edit input: pricing, languages, module data and resource limits.
$detailarrayThe record from **before** the update.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.updated', 10, function ($id, $input, $detail) {
Acme::syncCatalog($id, $input, $detail);
});
```
#### Stopping a product deletion
gateproduct.delete
`AdminProducts` before the write
Runs before a product is deleted.
Parameters 2
$idintThe id of the product to be deleted.
$detailarrayThe product record: type, module and group.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.delete', 10, function ($id, $detail) {
if (Acme::hasLiveServices($id)) return 'Live services still run on this product.';
return null;
});
```
#### Following a product deletion
actionproduct.deleted
`AdminProducts` after deletion
Runs after the product is deleted.
Parameters 2
$product_idintThe id of the deleted product.
$detailarrayIts last state. The record is gone: take what you need from here.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.deleted', 10, function ($product_id, $detail) {
Acme::dropCatalogItem($product_id);
});
```
#### Following a product status change
actionproduct.status_changed
`AdminProducts` one product
Runs when a product is opened for sale or closed.
Parameters 2
$product_idintThe product id.
$statusstringThe new state: `active` or `inactive`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.status_changed', 10, function ($product_id, $status) {
Acme::setCatalogVisible($product_id, $status === 'active');
});
```
#### Following a bulk action
actionproduct.bulk_action_applied
`AdminProducts` one call, many products
Runs when an action is applied to several products at once from the list. Unlike the single status event, this is **one call**, not one per product.
Parameters 2
$actionstringThe action applied: `active` or `inactive`.
$idsarrayThe ids of the products handled.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.bulk_action_applied', 10, function ($action, $ids) {
// One call, many products: the single status event does not fire here.
Acme::bulkVisibility($ids, $action === 'active');
});
```
### Pitfalls
> **A zero in the create event means it failed**
>
> The new product id can arrive as **zero**, which means no product was created. A listener that uses the id straight away then works on a record that is not there. Check it on the first line.
> **A bulk action does not raise the single status event**
>
> When an action reaches many products from the list, **only the bulk event** fires. Work hung on the single status hook never runs on that path; listen on both.
### Related Articles
- Product Hooks
- [Service Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Product Data and Catalogue Hooks
https://dev.wisecp.com/en/product-data-hooks
The eight hooks over product data, the catalogue, the card lists and stock.
### Overview
Product data flows two ways: through the save filter **on the way in**, and through the read filter **on the way out**. The second is a hot path and its result goes into the cache.
The rest build the lists a customer sees: catalogue plans, related products, software cards. The stock hook stands apart; it is moved not by an administrator but by an **order**.
### Reference
#### Changing the product data before it is saved
filterproduct.save_data
`AdminProducts` passed by link
Runs before the product data is written. This is how you hold one pricing policy in one place.
Parameters 2
$inputarrayby linkThe data to be written: type, options, module data, languages, pricing and tax.
$detailarrayThe existing record before the change.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.save_data', 10, function (&$input, $detail) {
// Hold the pricing policy in one place.
$input['pricing'] = Acme::applyMargin($input['pricing'] ?? []);
});
```
#### Changing a product as it is read
filterproduct.get
`Products::get` the result is cached
Runs after a product is read from the database. **Every** product read passes here: the catalogue, the basket, the service detail.
Parameters 2
$productarrayby linkThe resolved product row with its options and module data unpacked. When no product was found an **empty array** arrives; look before you reach into it.
$contextarrayThe id asked for and the language.
Return 1
voidThe return is ignored; you write over the product. ? The array you change **goes into the cache**: a mistake here shows up not on one read but on every read that follows.
Listener PHP
```php
Hook::add('filter:product.get', 10, function (&$product, $context) {
// A product that was not found arrives as an EMPTY array.
if (!$product) return;
$product['acme_badge'] = Acme::badgeFor((int) ($context['id'] ?? 0));
});
```
#### Changing the product configuration fields
filterproduct.config_options
`AdminProducts` empty means no form
Runs before the configuration fields offered by the module appear.
Parameters 3
$config_optionsarrayby linkThe field definitions to be shown.
$moduleobjectThe product module instance.
$module_dataarrayThe current module data of the product.
Return 1
voidThe return is ignored; you write over the definitions. If the array is **left empty** after the filter, no form appears at all: clearing the fields removes the form.
Listener PHP
```php
Hook::add('filter:product.config_options', 10, function (&$config_options, $module, $module_data) {
// Emptying the array removes the form entirely.
unset($config_options['legacy_option']);
});
```
#### Changing the catalogue plans
filterproduct.catalog_plans
`website/products` passed by link
Runs once the plan list on the catalogue page is prepared. Ordering, hiding and badging belong here.
Parameters 2
$plansarrayby linkThe plan list.
$ctxarrayContext: the category, the product kind and the layout.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.catalog_plans', 10, function (&$plans, $ctx) {
$plans = Acme::sortByPopularity($plans);
});
```
#### Changing the related product cards
filterproduct.related_products
`website/products` passed by link
Runs once the related product list under a product detail is built. The core default is up to four products from the same catalogue.
Parameters 2
$relatedarrayby linkThe card list.
$idintby linkThe id of the product on screen; this is the "related to what" context.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.related_products', 10, function (&$related, &$id) {
$related = Acme::recommendFor($id) ?: $related;
});
```
#### Changing the software card list
filterproduct.software_list
`website/products` passed by link
Runs once the card list of the software store is prepared.
Parameters 2
$outarrayby linkThe card list; each card carries a title, category, image and tags.
$ctxarrayContext: the currency the cards are priced in. The currency varies by visitor: if you produce a price, use this value rather than the default.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.software_list', 10, function (&$out, $ctx) {
// If you produce a price, use the currency from the context.
$out = Acme::attachOffers($out, (int) ($ctx['currency'] ?? 0));
});
```
#### Following a stock change
actionproduct.stock_changed
`Orders` driven by an order
Runs when the stock of a product moves. The move is not manual: an **order** becoming active, or ceasing to be, drives it.
Parameters 4
$product_idintThe product id.
$deltaintWhich way it moved: **minus one** means an order became active and stock came down, **plus one** means an order left and stock returned.
$new_stockintThe new stock written. It never goes below zero: expect no negative value.
$order_idintThe order that drove the change.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.stock_changed', 10,
function ($product_id, $delta, $new_stock, $order_id) {
// Stock never goes below zero.
if ($new_stock === 0) Acme::alertOutOfStock($product_id);
});
```
#### Changing per-country message pricing
filterproduct.intl_sms_country_pricing_save
`AdminProducts` passed by link
Runs before international text message prices are saved.
Parameters 1
$current_listarrayby linkCountry code against price: cost, selling amount, currency and status.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.intl_sms_country_pricing_save', 10, function (&$current_list) {
foreach ($current_list as $code => $row)
$current_list[$code]['amount'] = Acme::markup((float) ($row['cost'] ?? 0));
});
```
### Pitfalls
> **The read filter result goes into the cache**
>
> A change you make in the product read filter is **kept** and comes back on later reads. A mistake here shows up not on one page but everywhere until the cache is cleared.
> **An emptied configuration removes the form**
>
> If the array is empty after the configuration fields filter, **no form appears at all**. Clearing everything while meaning to hide one field leaves the administrator unable to configure the product.
### Related Articles
- Product Hooks
- [Service Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Product Group and Add-on Hooks
https://dev.wisecp.com/en/product-group-hooks
The seven hooks over groups, categories, add-ons and requirements.
### Overview
The structures around products live here: the **groups** that hold them, the **add-ons** sold beside them and the **requirements** asked for during an order.
Two shapes surprise. Group options arrive as an array or as text depending on the context. And the category gate receives not one record but a **batch**, which may include deletions.
### Reference
#### Changing the group data
filterproduct.group_save_data
`AdminProducts` options in two shapes
Runs before a product group or category is saved.
Parameters 3
$set_dataarrayby linkThe data to be written: status, visibility, type and options. ? The **shape of the options field depends on the context**: an array on a constant group, text elsewhere. Reading it as an array without checking fails.
$categorystringThe category context; empty for a top group, filled for a category kind.
$detailarrayThe existing record; empty on a new one.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.group_save_data', 10, function (&$set_data, $category, $detail) {
// Options may be an array or text: check the type first.
if (!is_array($set_data['options'] ?? null)) return;
$set_data['options']['acme_tag'] = Acme::tagFor($category);
});
```
#### Following a group being saved
actionproduct.group_saved
`AdminProducts` zero on a constant record
Runs after a product group or category is saved.
Parameters 3
$idintThe id of the saved record. On a constant category record it can arrive as **zero**.
$is_newboolTrue when newly created.
$categorystringThe category kind; empty means a top group.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.group_saved', 10, function ($id, $is_new, $category) {
// On a constant category the id can be ZERO.
if ($id) Acme::refreshGroupMenu($id);
});
```
#### Stopping a group deletion
gateproduct.group_delete
`AdminProducts` before the write
Runs before a product group or category is deleted.
Parameters 3
$idintThe id to be deleted.
$categorystringThe category context.
$detailarrayThe language record of what goes, title included.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.group_delete', 10, function ($id, $category, $detail) {
if (Acme::groupHasProducts($id)) return 'A group holding products cannot be deleted.';
return null;
});
```
#### Stopping a batch category operation
gateproduct.category_save
`AdminProducts` a batch of operations
Runs before add-on or requirement categories are saved. What arrives is not one record but **a batch**: one request can hold creations, updates and deletions together.
Parameters 2
$typestringThe category kind: `addon` or `requirement`.
$categoriesarrayThe operations to apply, each carrying its kind and an id or a title. A deletion can sit in this list too: a check that only looks at creations misses it.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.category_save', 10, function ($type, $categories) {
// The batch may hold DELETIONS too: walk all of them.
foreach ($categories as $op)
if (($op['action'] ?? '') === 'delete' && Acme::categoryInUse((int) ($op['id'] ?? 0)))
return 'A category in use cannot be deleted.';
return null;
});
```
#### Changing the add-on data
filterproduct.addon_save_data
`AdminProducts` passed by link
Runs before a product add-on is saved.
Parameters 2
$addonDataarrayby linkThe add-on data to be written: category, status, rank, tax exemption and the product it is tied to.
$detailarrayThe existing record; empty on a new one.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.addon_save_data', 10, function (&$addonData, $detail) {
$addonData['status'] = Acme::allowedAddon($addonData) ? ($addonData['status'] ?? 0) : 0;
});
```
#### Stopping an add-on deletion
gateproduct.addon_delete
`AdminProducts` before the write
Runs before a product add-on is deleted.
Parameters 2
$idintThe id of the add-on to be deleted.
$detailarrayThe add-on record.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.addon_delete', 10, function ($id, $detail) {
if (Acme::addonInUse($id)) return 'An add-on live on a customer cannot be deleted.';
return null;
});
```
#### Stopping a requirement deletion
gateproduct.requirement_delete
`AdminProducts` before the write
Runs before a product requirement is deleted. Requirements are what a customer is asked for during an order, so removing one touches **orders already waiting**.
Parameters 2
$idintThe id of the requirement to be deleted.
$detailarrayThe requirement record.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.requirement_delete', 10, function ($id, $detail) {
if (Acme::pendingOrdersNeed($id)) return 'Orders still waiting use this requirement.';
return null;
});
```
### Pitfalls
> **The shape of group options depends on context**
>
> The options field arrives as an **array** on a constant group record and as **text** otherwise. Reading it as an array without checking raises an error; test the type on the first line.
> **The category gate gets a batch, not one record**
>
> One request can hold creations, updates and **deletions** together. A check that only looks at creations misses the deletion sitting in the same request.
### Related Articles
- Product Hooks
- [Service Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Server Record Hooks
https://dev.wisecp.com/en/server-record-hooks
The eight hooks over server records, server groups and imports.
### Overview
Server records hold the details of the machines services are built on. Saving, updating, deleting and importing all live here.
? One distinction matters: **in the save filter the password is in the clear**, while in the events it is encrypted. The filter sits ahead of the encryption.
### Reference
#### Changing the server data before it is saved
filterproduct.server_save_data
`AdminProducts` password IN THE CLEAR
Runs before a server record is written. This is the point **before** the access details are encrypted.
Parameters 3
$set_dataarrayby linkThe server data to be written: name, address, username, **password**, name servers, capacity and access key. ? The password is **in the clear** here (encryption happens after this filter). Writing the record as it stands into a log, an outside service or a table of your own leaks that password in plain text.
$typestringThe server module type.
$detailarrayThe existing record; empty on a new one.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.server_save_data', 10, function (&$set_data, $type, $detail) {
// THE PASSWORD IS IN THE CLEAR HERE: do not write the record anywhere as it stands.
$set_data['ns1'] = Acme::defaultNs(1);
$set_data['ns2'] = Acme::defaultNs(2);
});
```
#### Following a server being added
actionproduct.server_created
`AdminProducts` password encrypted
Runs after a new server record is created.
Parameters 3
$idintThe id of the new server.
$set_dataarrayThe saved data. Unlike in the filter the password here is **encrypted**: you cannot read and use it.
$typestringThe server module type.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.server_created', 10, function ($id, $set_data, $type) {
// The password is encrypted here: give monitoring only the address.
Acme::addMonitor($id, $set_data['ip'] ?? '');
});
```
#### Following a server update
actionproduct.server_updated
`AdminProducts` before and after in hand
Runs after a server record is updated.
Parameters 4
$idintThe server id.
$set_dataarrayThe new data; the password is encrypted.
$typestringThe new module type.
$detailarrayThe record from **before** the update, there to measure the difference.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.server_updated', 10, function ($id, $set_data, $type, $detail) {
// Move monitoring when the address changed.
if (($detail['ip'] ?? '') !== ($set_data['ip'] ?? ''))
Acme::moveMonitor($id, $set_data['ip'] ?? '');
});
```
#### Stopping a server deletion
gateproduct.server_delete
`AdminProducts` before the write
Runs before a server record is deleted. The record goes; **the machine and the accounts on it stay**.
Parameters 2
$idintThe id of the server to be deleted.
$detailarrayThe server record: name, address and type.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.server_delete', 10, function ($id, $detail) {
// The record goes but the accounts on the machine remain.
if (Acme::serverHasServices($id)) return 'Live services still run on this server.';
return null;
});
```
#### Following a server being deleted
actionproduct.server_deleted
`AdminProducts` after deletion
Runs after the server record is deleted.
Parameters 2
$iintThe id of the deleted server.
$detailarrayThe record as it stood at deletion.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.server_deleted', 10, function ($i, $detail) {
Acme::dropMonitor($i);
});
```
#### Following an import from a server
actionproduct.server_imported
`AdminProducts` a list of summary text
Runs after the accounts on a server are brought in as services.
Parameters 2
$serverarrayThe server record the import ran against.
$importedarrayA summary of the services created. Each entry is **text**, not a record: it holds the name and id together. If you need the id, query the service rather than parsing the text.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:product.server_imported', 10, function ($server, $imported) {
// The entries are TEXT, not records.
Acme::notifyOps(count($imported) . ' services imported from ' . ($server['name'] ?? ''));
});
```
#### Changing server group data
filterproduct.server_group_save_data
`AdminProducts` servers as a text list
Runs before a server group is saved.
Parameters 2
$dataarrayby linkThe group data to be written: name, fill type and its servers. The server list is **comma-separated text, not an array**: split it before treating it as one.
$detailarrayThe existing record; empty on a new one.
Return 1
voidThe return is ignored; you write over the data.
Listener PHP
```php
Hook::add('filter:product.server_group_save_data', 10, function (&$data, $detail) {
// The server list is COMMA TEXT, not an array.
$ids = array_filter(explode(',', (string) ($data['servers'] ?? '')));
$data['servers'] = implode(',', Acme::onlyHealthy($ids));
});
```
#### Stopping a server group deletion
gateproduct.server_group_delete
`AdminProducts` before the write
Runs before a server group is deleted.
Parameters 2
$idintThe id of the group to be deleted.
$detailarrayThe group record.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:product.server_group_delete', 10, function ($id, $detail) {
if (Acme::groupBoundToProducts($id)) return 'Products are still bound to this group.';
return null;
});
```
### Pitfalls
> **In the save filter the password is in the clear**
>
> The server save filter runs **before the encryption**: the password field holds plain text. Writing that array to a log, sending it to an outside service or copying it into a table of your own leaks the server password in the clear. In the events the same field is encrypted.
> **Deleting the record does not empty the machine**
>
> The deletion removes only the **record**. The accounts, domains and data on the server stay where they are; the system stops knowing about them. The delete gate is your last chance to notice.
### Related Articles
- Product Hooks
- [Service Hooks](https://dev.wisecp.com/en/service-lifecycle-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
# Hooks / Invoicing and Payment
## Invoice Lifecycle Hooks
https://dev.wisecp.com/en/invoice-lifecycle-hooks
Eight hooks from an invoice being raised to it being deleted: the creation gate, two separate creation events, status changes and deletion.
### Overview
The first thing to watch on the invoice hooks is that there are **two separate creation events**. One runs on renewal invoices alone, the other on **every** invoice. Their names look alike and they are often mixed up.
The second is where the money sits: raising an invoice is not taking payment. Payment arrives on its own hooks and the status settles when it turns **paid**.
### Reference
#### Skipping a renewal invoice
gateinvoice.create
`cronjobs/InvoiceGenerate` the job returns cancelled
Runs before a renewal invoice is raised. This gate sits in a scheduled task, so stopping it **raises no error** and skips the job.
Parameters 3
$target_typestring`service` or `addon`.
$target_idintThe id of the record being invoiced.
$duedatestringThe renewal due date.
Return 1
stringA non-empty string **skips** the invoice: the job ends as cancelled and your text is recorded as **the reason**. The customer sees nothing; the invoice is never raised.
Listener PHP
```php
Hook::add('gate:invoice.create', 10, function ($target_type, $target_id, $duedate) {
// Raising a renewal while a cancellation is open only annoys the customer.
if ($target_type === 'service' && Acme::cancelPending($target_id))
return 'A cancellation is open; no renewal invoice was raised.';
return null;
});
```
#### Changing the invoice record before it is written
filterinvoice.create_payload
`Hook::runRefs` by reference
Runs before the invoice row is written to the database.
Parameters 1
$dataarrayrefThe record about to be written: `user_id`, `user_data`, `currency`, `status`, the totals, `pmethod`. The JSON fields are **already encoded** here; do not expect a raw array.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:invoice.create_payload', 10, function (&$data) {
// Add your own reference; the JSON fields arrive encoded already.
$data['notes'] = trim(($data['notes'] ?? '') . ' ' . Acme::stamp());
});
```
#### Catching every invoice
actioninvoice.created.any
`Invoices::create()` all of them
Runs after **every** invoice is written: renewals, manual ones, order invoices, all of them.
Parameters 2
$invoice_idintThe new invoice id. Where the write failed it arrives as `0`, so check before using it.
$dataarrayThe data that was written, with its JSON fields encoded.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.created.any', 10, function ($invoice_id, $data) {
if ($invoice_id === 0) return; // the write failed
Accounting::mirror($invoice_id, $data);
});
```
#### Catching a renewal invoice
actioninvoice.created
`cronjobs/InvoiceGenerate` renewals only
Runs after a renewal invoice was raised. **Not for every invoice**: manual and order invoices do not arrive here.
Parameters 1
$invoice_idintThe id of the invoice raised or merged into. Several renewals can have been merged into one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.created', 10, function ($invoice_id) {
// These are renewals ONLY; for all invoices use the .any hook.
Dunning::scheduleReminder((int) $invoice_id);
});
```
#### Catching a manually raised invoice
actioninvoice.created_manually
`AdminInvoices` an operator raised it
Runs where an operator raised an invoice from the panel.
Parameters 2
$invoice_idintThe id of the raised invoice.
$dataarrayThe invoice data.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.created_manually', 10, function ($invoice_id, $data) {
// A manual invoice is reported apart from the automatic ones.
Accounting::tagManual((int) $invoice_id);
});
```
#### Stopping an invoice status change
gateinvoice.status_change
`Invoices::change_status()` both states
Runs before an invoice status changes.
Parameters 4
$invoicearrayThe invoice record, decoded.
$statusstringThe target: `paid`, `unpaid`, `cancelled`, `refund`, `waiting`.
$old_statusstringThe current status.
$optionsarrayThe transition options: notification, payment method, refund route, who is acting. Context you cannot change.
Return 1
stringA non-empty string **stops** the change; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:invoice.status_change', 10,
function ($invoice, $status, $old_status, $options) {
// Taking a paid invoice back breaks the books.
if ($old_status === 'paid' && $status === 'unpaid')
return 'A paid invoice cannot go back to unpaid.';
return null;
});
```
#### Following an invoice status
actioninvoice.status_changed
`Invoices::change_status()` a freshly read record
Runs after the status was written.
Parameters 4
$invoicearrayThe invoice **read afresh** after the write. Unlike many other hooks, the record here is **current**.
$statusstringThe new status.
$old_statusstringThe previous status.
$optionsarrayThe transition options: payment method, refund route, who acted, notification.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.status_changed', 10,
function ($invoice, $status, $old_status, $options) {
// Did money REALLY arrive? React to the move into paid alone.
if ($status === 'paid' && $old_status !== 'paid')
Accounting::settled((int) ($invoice['id'] ?? 0), $options['pmethod'] ?? '');
});
```
#### Stopping an invoice delete
gateinvoice.delete
`Invoices::delete()` it may be a legal record
Runs before an invoice is deleted.
Parameters 2
$idintThe id of the invoice to be deleted.
$invoicearrayThe invoice record: `status`, `taxed`, `total`. Deleting a formalised invoice leaves no legal trail; check these fields.
Return 1
stringA non-empty string **stops** the delete; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:invoice.delete', 10, function ($id, $invoice) {
// A formalised invoice is not deleted; it is cancelled.
if (!empty($invoice['taxed'])) return 'A formalised invoice cannot be deleted.';
return null;
});
```
#### Following an invoice deletion
actioninvoice.deleted
`Invoices::delete` after deletion
Runs after an invoice is deleted. The record is gone, so the snapshot you hold is the last copy of it.
Parameters 2
$idintThe id of the deleted invoice.
$invoicearrayThe snapshot from **before** the deletion. You cannot go back to the database for it; take what you need from here.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.deleted', 10, function ($id, $invoice) {
// The record is gone: take what you need from the snapshot.
Acme::voidInAccounting($id, $invoice['number'] ?? '');
});
```
#### Following lines being split off
actioninvoice.items_split
`AdminInvoices` two invoices
Runs after lines are moved from one invoice into a new one. There are two invoices now.
Parameters 3
$source_invoice_idintThe invoice the lines came from.
$new_invoice_idintThe newly created invoice.
$item_idsarrayThe ids of the lines that moved.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.items_split', 10,
function ($source_invoice_id, $new_invoice_id, $item_ids) {
// Both invoices need to reach accounting separately.
Acme::resync($source_invoice_id);
Acme::resync($new_invoice_id);
});
```
#### Following a renewal invoice being made
actioninvoice.renewal_generated
`generate_renewal` renewal
Runs after a renewal invoice is made, or after a line joins one that already exists. Both services and add-ons land here.
Parameters 3
$invoice_idintThe id of the invoice made or joined.
$target_typestring`service` or `addon`.
$targetarrayThe record being renewed. One invoice can take several lines: the hook fires per line while the invoice id stays the same.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.renewal_generated', 10,
function ($invoice_id, $target_type, $target) {
// The same invoice can arrive more than once: make this safe to repeat.
Acme::noteRenewal($invoice_id, $target_type, (int) ($target['id'] ?? 0));
});
```
#### Following a payment reminder
actioninvoice.reminder_sent
`cronjobs` on each reminder
Runs after a payment reminder goes out. It can fire more than once for the same invoice, because reminders repeat.
Parameters 1
$invoicearrayThe invoice reminded about: its number, owner, total, status and due date.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.reminder_sent', 10, function ($invoice) {
// Nudge over a second channel as well.
Acme::smsReminder((int) ($invoice['user_id'] ?? 0), $invoice['number'] ?? '');
});
```
#### Following a customer opening an invoice
actioninvoice.viewed_by_client
`website/invoices` on every opening
Runs when a customer views an invoice. Knowing an invoice was opened is a useful signal for reminder and collection flows.
Parameters 3
$invoicearrayThe invoice record.
$idintThe id of the invoice.
$ctxarrayThe viewing context. To add data to the template use the view data filter that runs right after, not this hook.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.viewed_by_client', 10, function ($invoice, $id, $ctx) {
// Knowing it was read softens the collection flow.
Acme::markSeen($id, (int) ($invoice['user_id'] ?? 0));
});
```
#### Stopping a status change
gateinvoice.update_status
`AdminInvoices` before the write
Runs while an administrator changes an invoice status by hand. Marking paid, cancelling and refunding all pass through this gate.
Parameters 4
$idintThe invoice id.
$statusstringThe target status: `paid`, `unpaid`, `refund` or `cancelled`.
$pmethodstringThe method chosen when marking as paid.
$refund_methodstringThe method chosen when refunding.
Return 1
string|null**A non-empty text blocks the change** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:invoice.update_status', 10,
function ($id, $status, $pmethod, $refund_method) {
// No manual refunds once the period is closed.
if ($status === 'refund' && Acme::periodClosed($id))
return 'This period is closed, so the refund belongs in accounting.';
return null;
});
```
#### Stopping a share link
gateinvoice.share_view
`ClientInvoices` access without login
Runs when an invoice is opened through a share link. Whoever opens it **may not be logged in**: the only thing standing behind that access is the secret in the address.
Parameters 5
$invoicearrayThe resolved invoice record.
$idintThe invoice id.
$ownerintThe account that owns the invoice.
$tokenstringThe share value. Keep it out of your own records: whoever sees it can open both the invoice and the payment page.
$isOwnerboolWhether the opener is the signed-in owner. A false here means access without a session; tighten your check accordingly.
Return 1
string|null**A non-empty text cuts the access**: the view becomes a not-found page and the payment is blocked. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:invoice.share_view', 10,
function ($invoice, $id, $owner, $token, $isOwner) {
// Hold access without a session to your own address list.
if (!$isOwner && !Acme::ipAllowed()) return 'access denied';
return null;
});
```
#### Changing the customer details on an invoice
filterinvoice.client_details
`AdminInvoices` passed by link
Runs once the customer and address details are prepared for an invoice, before they are saved. What you write here becomes a permanent part of the invoice.
Parameters 2
$merged_dataarrayby linkWhat goes onto the invoice: name, surname, email, tax number, address.
$invoicearrayThe invoice being edited.
Return 1
voidThe return is ignored; you write over the array. An invoice is an archive document: a wrong value written here does not correct itself later, it stays with the invoice.
Listener PHP
```php
Hook::add('filter:invoice.client_details', 10, function (&$merged_data, $invoice) {
// Match the company title to the official name in accounting.
$official = Acme::officialName($merged_data['company_tax_number'] ?? '');
if ($official !== '') $merged_data['company'] = $official;
});
```
### Pitfalls
> **Two creation events, two different scopes**
>
> The plainly named event runs on **renewals only**, while the one ending in `.any` runs on **every** invoice. An accounting mirror, an outside sync or anything wanting a full count belongs on `.any` — otherwise manual and order invoices slip past quietly.
> **A zero id means the write failed**
>
> The `.any` event runs **even where the database write failed**, with the id arriving as `0`. Using it unchecked means writing against an invoice that does not exist.
> **Raising an invoice is not taking money**
>
> On the creation hooks the invoice is **unpaid**. Opening a service, switching an add-on on or saying "thank you" does not belong here. Money arrives when the status turns **paid**.
> **A change to the same status still runs the hook**
>
> The status event can run even where the new and old statuses are **the same**. You see it where a payment page is called twice or a job runs again. A listener reacting **without comparing** the two does its work twice.
### Related Articles
- Invoice and Payment Hooks
- [Service Renewal Hooks](https://dev.wisecp.com/en/service-renewal-hooks)
- Order Flow Hooks
## Payment Hooks
https://dev.wisecp.com/en/payment-hooks
The seven hooks where money truly arrives: the payment gates, the recorded payment row and automatic collection.
### Overview
An invoice does not have to be paid **in one go**: part payments add up and the invoice turns paid on its own once the balance clears. So the payment hooks run **more often** than the invoice status hook.
The second point is who paid. On a payment made through a share link **the payer has no identity**; the account id the hook hands you is the invoice's **owner**, not the person paying.
### Reference
#### Stopping a customer payment
gateinvoice.client_pay
`ClientInvoicePay` before money moves
Runs while a customer pays an invoice, before **any money moves**.
Parameters 4
$invoicearrayThe invoice record. The currency sits on the record itself; no separate parameter arrives.
$uidintThe invoice **owner**. Still the owner on a shared payment; it never points at the payer.
$methodarrayThe resolved payment method: the flow, the fee rate, the raw balance, bank accounts, gateway details.
$shareboolWhether this is a payment through a share link. With `true` there is **no session** and the payer is unknown.
Return 1
stringA non-empty string **stops** the payment: no fee is booked, no balance is taken, and no payment record is opened.
Listener PHP
```php
Hook::add('gate:invoice.client_pay', 10, function ($invoice, $uid, $method, $share) {
// On a shared payment the payer is unknown: shape your risk rules for that.
if ($share && (float) ($invoice['total'] ?? 0) > 5000)
return 'This amount cannot be paid through a share link.';
return null;
});
```
#### Stopping a bulk payment
gateinvoice.bulk_pay
`ClientInvoicePay` the currency arrives separately
Runs while a customer pays several invoices together.
Parameters 3
$invoicesarrayThe invoices about to be paid.
$cidintThe currency of the selection. Unlike the single payment gate it arrives as **its own parameter**, because the selection is gathered in one currency.
$methodarrayThe resolved payment method.
Return 1
stringA non-empty string **stops** the bulk payment.
Listener PHP
```php
Hook::add('gate:invoice.bulk_pay', 10, function ($invoices, $cid, $method) {
if (count($invoices) > 50) return 'At most 50 invoices are paid at once.';
return null;
});
```
#### Changing the payment row before it is written
filterinvoice.payment_data
`Hook::runRefs` by reference
Runs before the payment row is written. **After that row** the invoice can turn paid on its own.
Parameters 2
$payment_rowarrayrefThe payment about to be written: `owner_id`, `amount_in`, `currency`, `rate`, `fees`, `pmethod`, `transaction_id`, `paid_at`.
$invoicearrayThe invoice the payment applies to.
Return 1
voidThe value changes **by reference**; the return is not read. Changing the amount decides whether the invoice counts as paid.
Listener PHP
```php
Hook::add('filter:invoice.payment_data', 10, function (&$payment_row, $invoice) {
// Carry your own reference; changing the amount decides the paid outcome.
$payment_row['transaction_id'] = Acme::ref($payment_row['transaction_id'] ?? '');
});
```
#### Learning that a payment was recorded
actioninvoice.payment_recorded
`Invoices` it can be partial
Runs after the payment row was written. The invoice can **still be unpaid** at this point.
Parameters 3
$payment_idintThe id of the new payment record.
$invoice_idintThe invoice the payment went to.
$paymentarrayThe recorded payment: amount, currency, rate, method, transaction number, time, fees, who recorded it. The amount is **not necessarily the whole invoice**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.payment_recorded', 10,
function ($payment_id, $invoice_id, $payment) {
// It can be partial: check the balance before saying "invoice closed".
Accounting::received($invoice_id, (float) ($payment['amount_in'] ?? 0));
});
```
#### Following a payment added
actioninvoice.payment_added
`AdminInvoices` flat parameters
Runs after a payment was added to an invoice. Unlike the previous hook the values arrive **separately**.
Parameters 5
$invoice_idintThe invoice id.
$amountfloatThe amount, in the **invoice's** currency.
$currencyIdintThe id of the invoice currency.
$pmethodstringThe payment method.
$txn_idstringThe external transaction number.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.payment_added', 10,
function ($invoice_id, $amount, $currencyId, $pmethod, $txn_id) {
Accounting::line($invoice_id, (float) $amount, (int) $currencyId, $pmethod);
});
```
#### Following a payment deleted
actioninvoice.payment_deleted
`AdminInvoices` the invoice id can be 0
Runs after a payment record was deleted.
Parameters 2
$payment_idintThe id of the deleted payment.
$invoice_idintThe invoice it belonged to. Where the payment was not tied to one it arrives as `0`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.payment_deleted', 10, function ($payment_id, $invoice_id) {
if ($invoice_id === 0) return; // tied to no invoice
Accounting::reversed($invoice_id, (int) $payment_id);
});
```
#### Following an automatic collection
actioninvoice.auto_payment_attempted
`cronjobs/InvoiceAutoPayment` the attempt outcome
Runs after an automatic payment was attempted — **whether it worked or not**.
Parameters 3
$invoice_idintThe invoice attempted.
$final_statusstringThe outcome: `paid` or `unpaid`. Read the attempt's success from here.
$resultarrayThe step-by-step outcome: the balance step and the card step separately (`outcome`, `amount`, `error`), plus the starting and closing balance. Why a card failed is answered here.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.auto_payment_attempted', 10,
function ($invoice_id, $final_status, $result) {
// The card step's error arrives apart: tell the customer the real reason.
if ($final_status !== 'paid')
Dunning::failed($invoice_id, $result['card_step']['error'] ?? '');
});
```
#### Following a bank transfer notice
actioninvoice.bank_transfer_notified
`ClientInvoicePay` the customer says so
Runs when a customer says they sent a transfer. **No money has arrived**: this is a claim, and the invoice stays unpaid.
Parameters 3
$idintThe id of the invoice the notice is about.
$uidintThe **owner** of the invoice. With a share link somebody else may have sent the notice; this value still points at the owner.
$transferarrayThe notice payload: bank id and name, sender name and the **transfer reference**. That reference is the key for matching a bank statement: the invoice number for a single payment, one shared value for a bulk one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.bank_transfer_notified', 10, function ($id, $uid, $transfer) {
// No money yet, only a claim: match the statement on the reference.
Acme::watchStatement($transfer['rce'] ?? '', $id);
});
```
#### Following a cash record
actioninvoice.cash_recorded
`AdminMoney` cash record
Runs when an income or expense record is entered into the books by hand.
Parameters 4
$inex_idintThe id of the record created.
$typestring`income` or `expense`.
$amountfloatThe amount, stripped of formatting.
$currencyintThe id of the currency.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.cash_recorded', 10,
function ($inex_id, $type, $amount, $currency) {
Acme::postToLedger($inex_id, $type, $amount, $currency);
});
```
#### Following a refund through the gateway
actioninvoice.refunded_via_module
`AdminInvoices` through the gateway
Runs when an invoice is refunded through the payment gateway. The money really went back.
Parameters 2
$invoicearrayThe refunded invoice.
$pmethodstringThe payment module that handled it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.refunded_via_module', 10, function ($invoice, $pmethod) {
Acme::recordRefund((int) ($invoice['id'] ?? 0), $pmethod);
});
```
#### Following a payment method change
actioninvoice.gateway_changed
`AdminInvoices` method change
Runs after the payment method on an invoice changes.
Parameters 4
$idintThe invoice id.
$oldPmethodstringThe previous method; empty when none was set.
$newPmethodstringThe new method.
$invoicearrayThe invoice record **as it was before the change**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.gateway_changed', 10,
function ($id, $oldPmethod, $newPmethod, $invoice) {
// Close the pending session at the old gateway.
if ($oldPmethod !== '') Acme::dropPendingSession($id, $oldPmethod);
});
```
#### Following the auto-payment order of a card
actionpayment.card_autopay_changed
`AccountCards` chain change
Runs when a card moves within the auto-payment chain. That chain decides which card is tried first at renewal.
Parameters 3
$uidintThe owner of the card.
$cardIdintThe id of the record.
$actionstringWhat happened: `on` joined the chain, `off` left it, `promote` moved to the front.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.card_autopay_changed', 10, function ($uid, $cardId, $action) {
// An empty chain leaves the customer with no way to renew.
if ($action === 'off') Acme::warnIfChainEmpty($uid);
});
```
#### Following a subscription charge
actionsubscription.payment_recorded
`SubscriptionPoll` from the agreement
Runs after a subscription charge from the gateway is processed. The result need not be a success: rejected and repeated notices land here too.
Parameters 2
$identifierstringThe subscription identifier from the gateway.
$resultarrayThe outcome: its status, the invoice and payment ids, and a reason when there is one. The status may be `paid`, but it may equally be partial, duplicated or rejected. Do not assume success.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:subscription.payment_recorded', 10, function ($identifier, $result) {
// Do not assume success: the status may be a rejection.
if (($result['status'] ?? '') !== 'paid') return;
Acme::confirmCharge($identifier, (int) ($result['invoice_id'] ?? 0));
});
```
### Pitfalls
> **A payment record does not mean the invoice closed**
>
> Part payments add up as separate rows and the hook runs **on each**. The invoice turns paid only once the balance clears, and that moment shows on the **status hook**. Writing "payment arrived, open the service" here opens it **on an underpayment**.
> **On a shared payment the payer is unknown**
>
> The account id on the payment gate is **always the invoice owner**. The person paying through a share link can be somebody else entirely, with no session. Answering "who paid this" from that id points at **the wrong person**.
> **The two payment events have different shapes**
>
> One hands the payment over **in a single array**, the other gives the amount, currency, method and transaction number as **separate parameters**. Writing the wrong one drops the listener and looks like "it does not work".
> **Automatic collection has two steps**
>
> The balance is tried first, then the card. The result array reports **both separately**. Before telling a customer "your card was declined", read what the balance step did: the invoice may have been partly cleared from it.
### Related Articles
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- Invoice and Payment Hooks
- Order Flow Hooks
## Invoice Amount Hooks
https://dev.wisecp.com/en/invoice-amount-hooks
The eight hooks touching the numbers on an invoice: the items, the totals, the late fee, the renewal price and formalising.
### Overview
These hooks decide **what the customer pays**. They all work by reference and the value you write goes straight onto the invoice; a mistake in arithmetic here **becomes money**.
The last two differ: formalising turns an invoice into a **legal record**. After that the amount cannot change, the invoice cannot be deleted and its number is fixed.
### Reference
#### Changing the invoice totals
filterinvoice.totals
`Invoices` before they are saved
Runs after the totals were worked out, before they are written to the invoice.
Parameters 3
$totalsarrayrefThe totals about to be written: `subtotal`, `tax`, `additional_tax`, `pmethod_commission`, `total`, `discounts`. Changing one alone leaves the figures **out of step**; touching the subtotal means fixing the grand total too.
$invoicearrayThe invoice row: the tax rate, whether it is formalised, the currency, the commission rate. Context you cannot change.
$itemsarrayThe items used in the arithmetic. Context you cannot change.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:invoice.totals', 10, function (&$totals, $invoice, $items) {
// Having changed one figure, go over the GRAND TOTAL as well.
if (Acme::roundUp($invoice)) {
$totals['total'] = ceil((float) $totals['total']);
}
});
```
#### Changing the invoice discounts
filterinvoice.items
`AdminInvoices` the discount payload
Runs while an invoice is edited, before the discounts are saved.
Parameters 4
$idintThe id of the invoice being edited.
$invDiscountsarrayrefThe discounts about to be saved, including the per-item custom ones. Despite the name this is the **discount structure**, not a list of items.
$pendingCustomDiscountsarrayThe custom discounts keyed by item id.
$invoicearrayThe current invoice row.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:invoice.items', 10,
function ($id, &$invDiscounts, $pendingCustomDiscounts, $invoice) {
// The name misleads: this is the discount structure, not the items.
Acme::capDiscounts($invDiscounts, (float) ($invoice['subtotal'] ?? 0));
});
```
#### Changing the late fee
filterinvoice.late_fee_amount
`cronjobs/InvoiceLateFee` rounded afterwards
Runs after the late fee was worked out, before it is added to the invoice as an item.
Parameters 3
$feefloatrefThe raw late fee in the invoice's currency. It is **rounded again** after the filter, so no need to fuss over the last decimal here.
$invoicearrayThe invoice row: the subtotal, currency and owner.
$cyclestringThe fee cycle: once, or daily. On a daily cycle this hook runs **every day**.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:invoice.late_fee_amount', 10, function (&$fee, $invoice, $cycle) {
// On a daily cycle this runs every day: hold it under a ceiling.
$cap = (float) ($invoice['subtotal'] ?? 0) * 0.2;
if ($fee > $cap) $fee = $cap;
});
```
#### Following a late fee added
actioninvoice.late_fee_applied
`cronjobs/InvoiceLateFee` an item was created
Runs after the late fee was added to the invoice as an item.
Parameters 4
$invoice_idintThe invoice the fee went on.
$fee_amountfloatThe amount added — the **final** value after the filter.
$fee_typestring`percentage` or `fixed`.
$item_idintThe id of the created invoice item.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.late_fee_applied', 10,
function ($invoice_id, $fee_amount, $fee_type, $item_id) {
// Tell the customer the invoice grew; a silent rise becomes a complaint.
Notify::lateFee($invoice_id, (float) $fee_amount);
});
```
#### Changing the renewal price
filterinvoice.renewal_amount
`Invoices` the unit price
Runs after a service's renewal price was resolved.
Parameters 1
$resultarrayrefThe price result: `amount` (the **unit** price), `quantity`, `currency`, `taxexempt`, `additional_taxes`, `discounts`, `pricing_source`, `period_time`. The amount is **per unit**; the total is multiplied afterwards.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:invoice.renewal_amount', 10, function (&$result) {
// amount is the UNIT price: the core multiplies by quantity.
if (($result['pricing_source'] ?? '') === 'locked') return;
$result['amount'] = Acme::loyaltyPrice((float) $result['amount']);
});
```
#### Changing the renewal description
filterinvoice.renewal_description
`Invoices` it shows on the invoice
Runs after the renewal item's description was built.
Parameters 1
$descriptionstringrefThe item description. The text the customer reads on the invoice, so write it in their language.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:invoice.renewal_description', 10, function (&$description) {
$description .= ' — ' . Acme::periodNote();
});
```
#### Stopping an invoice being formalised
gateinvoice.formalize
`AdminInvoices` no way back
Runs before an invoice is formalised. After this step it can be **neither changed nor deleted**.
Parameters 2
$invoicearrayThe invoice about to be formalised.
$user_idintThe id of the person acting.
Return 1
stringA non-empty string **stops** the formalising; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:invoice.formalize', 10, function ($invoice, $user_id) {
// Formalising cannot be undone: not with tax details missing.
if (!Acme::taxDetailsComplete($invoice))
return 'Complete the tax details before formalising.';
return null;
});
```
#### Following a formalised invoice
actioninvoice.formalized
`AdminInvoices` read afresh
Runs after the invoice was formalised.
Parameters 2
$invoicearrayThe invoice **read afresh** with its formalised mark, including the document file where one was produced.
$user_idintThe id of the person who acted.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.formalized', 10, function ($invoice, $user_id) {
// A legal record now: send it to the books here, not earlier.
Accounting::submit($invoice);
});
```
#### Changing the list summary cards
filterinvoice.list_stats
`admin/invoices` passed by link
Runs after the summary cards above the invoice list are worked out. What you change reaches both the cards and the visual hook that adds to that area.
Parameters 2
$initial_statsarrayby linkThe card data: unpaid, paid and overdue, each with a formatted total and a count.
$stats_cardsarrayThe card setup: type and period.
Return 1
voidThe return is ignored; you write over the array.
Listener PHP
```php
Hook::add('filter:invoice.list_stats', 10, function (&$initial_stats, $stats_cards) {
// Keep reseller invoices out of the summary.
$initial_stats['unpaid']['formatted'] = Acme::excludeResellers($initial_stats['unpaid']);
});
```
#### Changing the invoice document font
filterinvoice.pdf_font
`Invoices::create_pdf` through the object
Runs while the invoice document is built. The default font cannot draw letters outside the Latin alphabet, so this is where you supply the right one.
Parameters 2
$pdfobjectThe document builder. Being an object it changes without a by-link mark: calling a method on it is enough.
$invoicearrayThe invoice record. It carries the customer’s stored language; it is a copy, so changing it has no effect.
Return 1
voidThe return is ignored. You make the change by calling a method on the object.
Listener PHP
```php
Hook::add('filter:invoice.pdf_font', 10, function ($pdf, $invoice) {
// The default font cannot draw letters outside the Latin alphabet.
if (($invoice['user_data']['lang'] ?? '') === 'ru') $pdf->setDefaultFont('dejavusans');
});
```
#### Adding a payment method logo
registerinvoice.module_logos
`templates/admin` returns one URL
Runs while the payment method badges are drawn on the invoice screen. Add the logo of your own method here.
Parameters 0
—It takes no parameters.
Return 1
string|nullYou return **a single address**, not markup: the template places it in an image. Return `null` when you have no logo to show. Empty text, zero and false are filtered out anyway.
Listener PHP
```php
Hook::add('register:invoice.module_logos', 10, function () {
// Return a single address, not markup.
return Acme::assetUrl('acme-pay.svg');
});
```
#### Following a customer applying a coupon
actioninvoice.coupon_applied_by_client
`ClientInvoices` applied by the customer
Runs after a customer applies a coupon to their own invoice. The discount is already worked in.
Parameters 4
$uidintThe customer who applied it.
$idintThe invoice id. The invoice itself is left out on purpose: by the time the hook runs the totals have moved, so a copy would be stale. Read it fresh if you need it.
$couponarrayThe coupon record. Its amount field may have shifted during the application.
$couponCtxarrayWhat the application produced: the discount, the currency and the lines it touched.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:invoice.coupon_applied_by_client', 10,
function ($uid, $id, $coupon, $couponCtx) {
// The invoice row is left out on purpose: read it fresh if you need it.
Acme::trackDiscount($uid, $coupon['code'] ?? '', (float) ($couponCtx['discount'] ?? 0));
});
```
### Pitfalls
> **Changing one figure does not fix the rest**
>
> Changing the subtotal on the totals filter and leaving the grand total as it was makes the invoice **disagree with itself**: the customer reads one figure and the payment asks for another. Touching one field means going over **the ones tied to it**.
> **The discount filter is mistaken for an item list**
>
> The name suggests items, and yet this filter hands you the **discount structure**. A listener expecting a list of items finds an array it does not know and quietly writes in the wrong place. Check what the second parameter is **from its entry**.
> **A daily late fee runs every day**
>
> Where the cycle is daily, the filter and the event run **again each day**. A rule with no ceiling turns an unpaid invoice **unpayable** within weeks. Sending a notification, mind that it does not go out daily either.
> **Formalising is a point of no return**
>
> A formalised invoice **cannot be deleted and its amount cannot change**. Sending to the books, reserving a number and archiving belong on the **formalised event**; work written earlier treats an invoice that is later cancelled as a legal record.
### Related Articles
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [Payment Hooks](https://dev.wisecp.com/en/payment-hooks)
- [Service Renewal Hooks](https://dev.wisecp.com/en/service-renewal-hooks)
## Payment Gateway Hooks
https://dev.wisecp.com/en/gateway-hooks
The eight hooks talking to a payment gateway: settlement, callbacks, stored cards and subscription collection.
### Overview
Talking to a gateway runs **both ways**. We ask for a charge, and the gateway answers either at once or later as a **callback**. That second route can arrive from a browser or straight from their servers.
On stored cards the card number **never reaches us**: the gateway keeps a token and we hold only the display details (last four digits, brand, expiry). Those are all the hooks receive.
### Reference
#### Following a settlement
actionpayment.settled
`PaymentGatewayModule` it can be pending
Runs after the settlement with the gateway completed.
Parameters 4
$modulePaymentGatewayModuleThe module object that settled.
$checkoutarrayThe checkout record **after the write**: its status is paid, with the settlement time and transaction number inside. `settled_status` can be `pending`, meaning the money is **not final yet**.
$resultarrayThe module's **raw** result: status, message, the paid mark, subscription details. It speaks the gateway's own language.
$responsearrayThe answer going back to the core: the status, the pending mark, the redirect address.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.settled', 10,
function ($module, $checkout, $result, $response) {
// It can be PENDING: open nothing before the money is final.
if (($checkout['data']['settled_status'] ?? '') !== 'successful') return;
Accounting::gatewaySettled($module->name, $checkout);
});
```
#### Following a callback
actionpayment.callback_returned
`PaymentGatewayModule` the record can be empty
Runs after the gateway's callback was interpreted.
Parameters 4
$modulePaymentGatewayModuleThe module that read the callback.
$checkoutarrayThe checkout record. Where the module could not resolve it, an **empty array** arrives: the callback may be forged or unmatched.
$settlearrayThe settlement result: status, redirect, message and the `already` mark. `already` means "this callback was handled before".
$is_s2sboolWhether the callback came **straight from their servers**. With `false` the customer's browser brought it, and they may never have opened that page.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.callback_returned', 10,
function ($module, $checkout, $settle, $is_s2s) {
// An empty checkout is an unmatched callback; check the repeat mark too.
if (!$checkout || !empty($settle['already'])) return;
Ops::note('gateway-callback', $module->name, $is_s2s ? 'server' : 'browser');
});
```
#### Stopping a card being stored
gatepayment.card_add
`AccountCards` no number arrives
Runs while a customer stores a card. **The card number never reaches this hook**; you decide on the account and module alone.
Parameters 3
$uidintThe account storing the card. Confirmed to be their own.
$moduleNamestringThe gateway module storing the card.
$autoPayboolWhether the card joins the automatic payment chain. Always `false` where the module does not support it.
Return 1
stringA non-empty string **stops** the card being stored.
Listener PHP
```php
Hook::add('gate:payment.card_add', 10, function ($uid, $moduleName, $autoPay) {
// The card number NEVER arrives here: decide on the account.
if (Acme::cardCount($uid) >= 5) return 'At most 5 cards are kept.';
return null;
});
```
#### Following a card stored
actionpayment.card_stored
`AccountCards` display details only
Runs after the card was stored at the gateway.
Parameters 4
$userIdintThe card's owner.
$cardIdintThe id of the stored card record.
$modulestringThe module that stored it.
$cardarray**Display details only**: the last four digits, brand, type, expiry month and year. The card number, the security code and the gateway token are **not here** and never will be.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.card_stored', 10, function ($userId, $cardId, $module, $card) {
// Display details only; never the number or the token.
Notify::securityEvent($userId, 'card-added', $card['ln4'] ?? '');
});
```
#### Following the default card
actionpayment.card_default_set
`AccountCards` auto-payment uses this one
Runs after a card was made the default.
Parameters 2
$uidintThe card's owner.
$cardIdintThe id of the card made default. Automatic payment tries this one from now on.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.card_default_set', 10, function ($uid, $cardId) {
Audit::note('card-default', (string) $uid, (string) $cardId);
});
```
#### Following a card removed
actionpayment.card_removed
`AccountCards` auto-payment is affected
Runs after a stored card was removed.
Parameters 2
$uidintThe card's owner.
$cardIdintThe id of the removed card.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.card_removed', 10, function ($uid, $cardId) {
// With the last card gone auto-payment stops quietly: tell the customer.
if (Acme::cardCount($uid) === 0) Notify::noCardLeft($uid);
});
```
#### Stopping a subscription cancellation
gatepayment.subscription_cancel
`AccountCards` the agreement at the gateway
Runs while a customer cancels the recurring agreement at the gateway.
Parameters 2
$uidintThe agreement's owner.
$idintThe id of the agreement being cancelled.
Return 1
stringA non-empty string **stops** the cancellation.
Listener PHP
```php
Hook::add('gate:payment.subscription_cancel', 10, function ($uid, $id) {
// Cancelling the agreement closes no service, it stops the payments: warn first.
if (Acme::activeServices($uid) > 0 && !Acme::confirmed($uid))
return 'You have live services; please confirm the cancellation.';
return null;
});
```
#### Following a subscription poll
actionpayment.subscription_polled
`cronjobs/SubscriptionPoll` it runs on a schedule
Runs after the scheduled task queried the agreements at the gateway.
Parameters 2
$subscriptionarrayThe agreement record that was polled.
$resultarrayThe result from the gateway. The poll runs on a schedule and arrives **many times** for one agreement.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.subscription_polled', 10, function ($subscription, $result) {
// It runs on a schedule: react to a CHANGE, not to every poll.
Acme::syncSubscription($subscription, $result);
});
```
#### Following gateway settings being saved
actionpayment.settings_saved
`PaymentGatewayModule` after the write
Runs after the settings of a payment module are saved.
Parameters 2
$module_namestringThe name of the module whose settings were saved.
$configarrayThe whole configuration written to disk. It holds API keys and secrets: keep it out of your own records and your logs.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.settings_saved', 10, function ($module_name, $config) {
// Carry the fact that it changed, NOT the configuration itself.
Acme::notifyOps('payment settings changed: ' . $module_name);
});
```
#### Adding a bank logo
filterpayment.bank_logo
`Payment` pattern map
Runs while the logo of the detected bank is chosen. Add your own bank list here.
Parameters 3
$bank_namestringThe bank name detected from the card.
$card_brandstringThe card brand.
$card_typestringThe card type: `debit` or `credit`.
Return 1
arrayYou return a **map**: the key is a fragment the bank name will contain, the value is the logo address. Returns are merged into the existing list. Matching is a substring search, not an exact one: a short key catches banks you did not mean.
Listener PHP
```php
Hook::add('filter:payment.bank_logo', 10,
function ($bank_name, $card_brand, $card_type) {
// The key is a substring search: a short one catches other banks too.
return ['Acme Bank' => Acme::assetUrl('acme-bank.svg')];
});
```
#### Taking over the card lookup
filterpayment.bin_lookup
`Payment` passed by link
Runs while the bank and type are resolved from the first digits of a card. Fill it in and the outside service is **never called**.
Parameters 2
$resultarray|falseby linkThe lookup result. Expected fields: country, card type, scheme, bank name and brand.
$bin_numberstringThe first six digits of the card.
Return 1
voidThe return is ignored; you write over the result. Leave it alone and the outside lookup carries on as normal. Wiring your own cache here saves a call on every payment.
Listener PHP
```php
Hook::add('filter:payment.bin_lookup', 10, function (&$result, $bin_number) {
// With a cache of your own there is no need to go outside.
$cached = Acme::binCache($bin_number);
if ($cached) $result = $cached;
});
```
#### Replacing the payment pane with your own
filterpayment.gateway_pane
`Checkout` passed by link
Runs while the gateway pane is prepared at the payment step. Put your own screen here and the classic payment page is skipped.
Parameters 2
$htmlstringby linkWhat will be drawn in the pane.
$ctxarrayby linkThe context.
Return 1
voidThe return is ignored. Leave the content **filled** and your screen is shown; leave it **empty** and the classic payment page takes over. Emptying it is a decision too.
Listener PHP
```php
Hook::add('filter:payment.gateway_pane', 10, function (&$html, &$ctx) {
// Filled means your screen, empty means the classic page.
$html = Acme::renderPane($ctx);
});
```
#### Following an agreement being cancelled
actionpayment.subscription_cancelled
`AccountSubscriptions` after cancellation
Runs after a payment agreement is cancelled. No further charge arrives from it.
Parameters 2
$subscription_idintThe id of the cancelled agreement.
$subarrayThe agreement row **as it was before the cancellation**: owner, module, identifier, currency and period.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.subscription_cancelled', 10, function ($subscription_id, $sub) {
// The services behind it now have no automatic charge.
Acme::warnUnpaidRisk((int) ($sub['user_id'] ?? 0));
});
```
#### Stopping a member being taken off an agreement
gatepayment.subscription_member_remove
`AccountSubscriptions` before removal
Runs before a service or add-on is taken off a payment agreement.
Parameters 6
$uidintThe owner of the agreement.
$subscription_idintThe id of the agreement.
$typestring`service` or `addon`.
$midintThe id of the member.
$memberarrayThe member row about to be removed. On an add-on the owner field holds the id of the **parent service**, not the user: read it accordingly.
$subarrayThe agreement row.
Return 1
string|null**A non-empty text blocks the removal** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:payment.subscription_member_remove', 10,
function ($uid, $subscription_id, $type, $mid, $member, $sub) {
// No removal while the commitment period still runs.
if (Acme::underCommitment($mid, $type)) return 'It cannot leave before the commitment ends.';
return null;
});
```
#### Following a member being taken off
actionpayment.subscription_member_removed
`AccountSubscriptions` after removal
Runs after the member is taken off the agreement.
Parameters 5
$typestring`service` or `addon`.
$idintThe id of the member.
$memberarrayThe member row **as it was before removal**. Its agreement field still holds the **old** value: that is where "which agreement did it leave" is answered.
$subarrayThe agreement row **before the change**; its status and amount are the old ones.
$historyarrayWhat the operation produced, the same record written to the history.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:payment.subscription_member_removed', 10,
function ($type, $id, $member, $sub, $history) {
// "Which agreement did it leave" lives in the old value.
Acme::detached($type, $id, (int) ($member['subscription_id'] ?? 0));
});
```
### Pitfalls
> **A settlement is not "the money arrived"**
>
> The settlement record can carry a **pending** status: the gateway took the transaction and has not finalised it. A listener opening a service without checking hands out **a free service** for a payment that later fails.
> **The record can be empty on a callback**
>
> Where the module cannot tie a callback to a checkout, the hook receives an **empty array**. That marks a forged or unmatched callback. The same callback can also arrive **again**; a listener ignoring the "handled before" mark does its work twice.
> **The card number reaches no hook**
>
> The stored-card hooks carry **display details only**: the last four digits, the brand, the expiry. The number, the security code and the token never reach us. You cannot write a rule that reads the card; build the decision on **the account**.
> **A browser return is not a reliable signal**
>
> Where a callback came **from their servers**, the gateway is speaking. From a browser, the customer may never have opened that page — closed it, lost the network, missed the redirect. Rest work that involves money on **the server callback**.
### Related Articles
- [Payment Hooks](https://dev.wisecp.com/en/payment-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- Order Flow Hooks
## Currency and Coupon Hooks
https://dev.wisecp.com/en/currency-and-coupon-hooks
The eight hooks over currency conversion, how amounts read, and coupons.
### Overview
The hooks here run on **every screen**. Currency conversion and amount formatting pass through every price the site shows, so heavy work here becomes **the whole site's** burden.
Coupons differ: they run rarely and touch **money directly**. The apply gate sits in the cart, and the save gate runs where an operator defines a coupon.
### Reference
#### Stopping a coupon being applied
gatemoney.coupon_apply
`Coupon::validate()` zero for a guest
Runs before a coupon is applied to the cart.
Parameters 3
$couponarrayThe coupon record: the code, the type (`percent`, `amount`, `fixed`), the rate or amount, the currency, the auto-apply and merge marks, the product limits.
$uidintThe cart's owner. On a guest checkout it arrives as **`0`**; remember that when writing a rule about the account.
$contextarrayThe pricing context: `items` (the priced cart lines), `subtotal`, `user_currency`.
Return 1
stringA non-empty string **refuses** the coupon; the text is shown to the customer as the error.
Listener PHP
```php
Hook::add('gate:money.coupon_apply', 10, function ($coupon, $uid, $context) {
// A guest arrives as 0: split the account rule on that first.
if ($uid === 0) return 'Please sign in to use this coupon.';
if (Acme::alreadyUsed($uid, $coupon['code'] ?? '')) return 'The coupon was used already.';
return null;
});
```
#### Stopping a coupon being saved
gatemoney.coupon.save
`AdminMoney` an operator defines it
Runs before an operator saves a coupon.
Parameters 4
$codestringThe coupon code.
$statearrayA snapshot of **every** value on the form: type, rate, amount, currency, limits. It is **not** the array about to be written; it is the raw form state.
$isEditboolWhether this is an edit or a new record.
$idintThe coupon id on an edit, `0` on a new one.
Return 1
stringA non-empty string **stops** the save.
Listener PHP
```php
Hook::add('gate:money.coupon.save', 10, function ($code, $state, $isEdit, $id) {
// A discount above 90 per cent is usually a typing slip.
if (($state['type'] ?? '') === 'percent' && (float) ($state['rate'] ?? 0) > 90)
return 'A discount above 90 per cent wants approval.';
return null;
});
```
#### Changing the coupon about to be saved
filtermoney.coupon.save_data
`Hook::runRefs` some fields get overwritten
Runs before the coupon data is written to the database.
Parameters 3
$dataarrayrefThe coupon data about to be written: code, type, rate, amount, currency, limits. On a new record `status` and the creation date are added **after** this filter, so what you write there is **overwritten**.
$isEditboolWhether this is an edit or a new record.
$idintThe coupon id, or `0`.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:money.coupon.save_data', 10, function (&$data, $isEdit, $id) {
// Do not write status on a new record: it is overwritten AFTER this filter.
$data['code'] = strtoupper((string) ($data['code'] ?? ''));
});
```
#### Following a coupon status
actionmoney.coupon.status_changed
`AdminMoney` a copy carries its source
Runs after a coupon's status changed.
Parameters 3
$coupon_idintThe id of the coupon affected.
$source_idintThe id of the source it was copied from. Not a copy means `0`; this is how you tell a copy apart.
$statusstringThe new status.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:money.coupon.status_changed', 10,
function ($coupon_id, $source_id, $status) {
// A filled source means this coupon is a copy.
if ($source_id > 0) Acme::linkCopy($coupon_id, $source_id);
});
```
#### Changing a currency conversion
filtermoney.exchange_rate
`Money::exChange()` it runs constantly
Runs after an amount was converted into another currency. It runs **on every conversion**.
Parameters 4
$convertedfloatrefThe result as worked out. What you write here is the **final** amount.
$amountfloatThe source amount.
$fromarrayThe source currency: code, rate, prefix, suffix.
$toarrayThe target currency: code, rate, prefix, suffix.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:money.exchange_rate', 10,
function (&$converted, $amount, $from, $to) {
// It runs on EVERY conversion: no queries, no remote calls here.
$converted = round($converted * (1 + Acme::MARGIN), 4);
});
```
#### Changing how an amount reads
filtermoney.format_output
`Money::formatter()` on every price
Runs after an amount was turned into text.
Parameters 2
$outputstringrefThe formatted text. A format you change on the server has to **match** what the browser side produces, or the figure visibly changes as the page loads.
$amountfloatThe raw amount being formatted.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:money.format_output', 10, function (&$output, $amount) {
// Where the browser side formats differently, the figure flickers on load.
if ((float) $amount === 0.0) $output = Acme::freeLabel();
});
```
#### Following a rate update
actionmoney.exchange_rates_updated
`cronjobs/ExchangeRates` the changed ones only
Runs after the exchange rates were updated.
Parameters 2
$changesarrayThe rates that **changed** in this run, keyed by currency code. With nothing changed an **empty array** arrives, and the hook still runs.
$localCodestringThe system's main currency code. The rates are expressed against it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:money.exchange_rates_updated', 10, function ($changes, $localCode) {
if (!$changes) return; // nothing moved this run
Ops::note('fx', $localCode . ': ' . implode(',', array_keys($changes)));
});
```
#### Stopping a currency being switched
gatemoney.currency.status_change
`AdminMoney` a wide effect
Runs before a currency is switched on or off.
Parameters 2
$currencyarrayThe currency record.
$statusstringThe state being asked for.
Return 1
stringA non-empty string **stops** the change.
Listener PHP
```php
Hook::add('gate:money.currency.status_change', 10, function ($currency, $status) {
// Switching off a currency in use leaves prices with nowhere to resolve.
if ($status !== 'active' && Acme::inUse($currency['id'] ?? 0))
return 'Live services use this currency; it cannot be switched off.';
return null;
});
```
#### Following a coupon being saved
actioncoupon.saved
`AdminMoney` create and edit
Runs when a coupon is created or edited. Both land on the same hook, and a parameter tells you which.
Parameters 4
$idintThe id of the coupon.
$codestringThe coupon code.
$isEditboolTrue when an existing coupon was edited, false when a new one was made.
$dataarrayThe saved fields: type, rate, amount, currency, validity cycles and usage limit.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:coupon.saved', 10, function ($id, $code, $isEdit, $data) {
// Announce only a new coupon to the campaign system.
if (!$isEdit) Acme::publishCampaign($code, $data);
});
```
#### Following a coupon being deleted
actionmoney.coupon.deleted
`AdminMoney` after deletion
Runs after a coupon is deleted.
Parameters 2
$coupon_idintThe id of the deleted coupon.
$couponarrayThe record before deletion. The coupon is gone: take the code from here if you need it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:money.coupon.deleted', 10, function ($coupon_id, $coupon) {
Acme::retireCampaign($coupon['code'] ?? '');
});
```
#### Following the base currency changing
actionmoney.currency.local_changed
`AdminMoney` base currency
Runs when the base currency of the system changes. This is a large change: every rate is now read against the new unit.
Parameters 2
$idintThe id of the currency that became the base.
$currencyarrayThe record of that currency, **read before the change**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:money.currency.local_changed', 10, function ($id, $currency) {
// Every rate is now read against the new unit.
Acme::rebaseReports($id);
});
```
#### Stopping a tax rule being saved
gatemoney.tax_rule.save
`AdminMoney` before the write
Runs before a tax rule is saved. A wrong rate reaches every new invoice, which makes a check here cheap.
Parameters 3
$country_idintThe country of the rule.
$state_idintThe state or city; a **zero** means the rule covers the whole country.
$ratefloatThe total rate worked out.
Return 1
string|null**A non-empty text blocks the save** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:money.tax_rule.save', 10, function ($country_id, $state_id, $rate) {
// A rate outside the sane range is usually a typing slip.
if ($rate < 0 || $rate > 40) return 'The tax rate falls outside the expected range.';
return null;
});
```
#### Following a tax rate change
actionmoney.tax_rates_changed
`AdminMoney` after the write
Runs after a tax rule is saved.
Parameters 3
$country_idintThe country of the rule.
$state_idintThe state or city; a zero covers the whole country.
$ratefloatThe new total rate.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:money.tax_rates_changed', 10, function ($country_id, $state_id, $rate) {
Acme::syncTaxTable($country_id, $state_id, $rate);
});
```
#### Adjusting a currency change
filtermoney.currency.save_data
`AdminMoney` passed by link
Runs while a currency is saved, before **only the changed fields** are written. What you hold is the difference, not the whole record.
Parameters 3
$setsarrayby linkThe difference about to be written. It **can arrive empty** when nothing changed; be ready for that.
$idintThe id of the currency.
$currencyarrayThe current record, with the values from before the difference.
Return 1
voidThe return is ignored; you write over the difference. A base currency switch is applied **after** this filter and adds further fields, so what you see here is not the final shape.
Listener PHP
```php
Hook::add('filter:money.currency.save_data', 10, function (&$sets, $id, $currency) {
// The difference can be empty: look first.
if (!$sets) return;
// Pin the rate to your own source.
if (isset($sets['rate'])) $sets['rate'] = Acme::officialRate($currency['code'] ?? '');
});
```
#### Changing how an amount is written
filtermoney.digit
`Money::format` the last return wins
Runs while an amount is formatted. **Every** money value in the system passes through here: invoices, the basket, lists, documents.
Parameters 4
$amountfloatThe raw amount.
$currencyarrayThe resolved currency record.
$symbolboolWhether the symbol is shown.
$exchangemixedThe conversion target, or false when there is none.
Return 1
string|nullWhat you return **replaces** the format, and the last return wins. Return **nothing** for calls you do not care about: `null` is skipped safely. But `''`, `0` and `false` are not skipped; they are assigned and the amount **comes out blank**.
Listener PHP
```php
Hook::add('filter:money.digit', 10, function ($amount, $currency, $symbol, $exchange) {
if (($currency['code'] ?? '') !== 'BTC') return; // do NOT return '': it blanks the amount
return number_format($amount, 8, '.', '');
});
```
#### Changing the fetched rates
filtermoney.exchange_rates_fetch
`Money` passed by link
Runs after rates come in from the outside source and before they are saved. You can add one, change one, or drop one you do not trust.
Parameters 3
$ratesarrayby linkCode against rate, read against the base currency.
$localCodestringThe code of the base currency the rates are read against.
$targetsarrayThe currencies to be synced.
Return 1
voidThe return is ignored; you write over the list.
Listener PHP
```php
Hook::add('filter:money.exchange_rates_fetch', 10,
function (&$rates, $localCode, $targets) {
// Write your own official source over the outside service.
$own = Acme::officialRates($localCode);
foreach ($own as $code => $rate) $rates[$code] = $rate;
});
```
#### Following recurring expenses being recorded
actionexpense.recurring_recorded
`cronjobs` once per round
Runs after the recurring expense rules are processed. It fires once for **the whole round**, not per expense.
Parameters 2
$entriesarrayThe rules handled in this round, each with its rule and record id, description, amount, currency and status.
$recordedintHow many expenses were added **successfully** this round. The hook does not fire when nothing was added, so this is always at least one.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:expense.recurring_recorded', 10, function ($entries, $recorded) {
// One call per round: send them to accounting in one batch.
Acme::pushExpenses($entries);
});
```
### Pitfalls
> **The rate and format hooks run on every price**
>
> A catalogue page shows hundreds of prices and these two hooks run **for each one**. A query, a file read or a remote call inside them slows the page hundreds of times over. Prepare what you need **once** and keep it in a static variable.
> **On a guest cart the account id is zero**
>
> The account id at the coupon gate arrives as `0` on a checkout with nobody signed in. A rule like "has this customer used the coupon before" treats **every guest as one person**. Split the zero case out before writing an account rule.
> **Some fields are overwritten after the coupon filter**
>
> On a new coupon the `status` and creation date are added **after the filter**. Values you write there vanish quietly — no error and no effect. To set a status, work from a hook that runs after the save.
> **Server and browser must format alike**
>
> The format filter runs **on the server**. Some figures on a page are rewritten by the browser, and where the two format differently the customer watches the number **visibly change** as the page loads. Changing a format means changing both sides.
### Related Articles
- [Invoice Amount Hooks](https://dev.wisecp.com/en/invoice-amount-hooks)
- Order Flow Hooks
- Invoice and Payment Hooks
# Hooks / Orders
## Cart Hooks
https://dev.wisecp.com/en/cart-hooks
Eight hooks from a customer filling a cart to the order being placed. The add gates, the pricing chain and the checkout step.
### Overview
Cart pricing is a **three-stage chain** and each stage has its own filter. The raw inputs come first, then the priced lines, then the summary. Knowing the order puts your rule on **the right link**.
Picking the wrong link fails quietly. Change a total on the item filter and the summary **works it out again**, writing over you.
### Reference
#### Stopping something going in the cart
gateorder.cart_add
`Cart` the product is validated
Runs before the product is written into the cart, with the product and cycle **already validated**.
Parameters 3
$productarrayThe product record: id, type, name, stock, add-ons, options. Already confirmed to be on sale.
$cyclestringThe billing cycle chosen. Confirmed to be one the product actually offers.
$itemarrayThe line about to be written: kind, product id, cycle, quantity, the configured mark, the options.
Return 1
stringA non-empty string **stops** the action; the text is shown to the customer as the error.
Listener PHP
```php
Hook::add('gate:order.cart_add', 10, function ($product, $cycle, $item) {
// The core checks stock; add your own business rule.
if (Acme::limitReached($product['id'] ?? 0))
return 'The daily order limit for this product is spent.';
return null;
});
```
#### Changing the raw inputs
filterorder.cart_inputs
`Orders::buildCart()` the first link
Runs on the raw order inputs, before pricing starts.
Parameters 2
$inputsarrayrefThe raw inputs, each with its own group (domain, product, add-on). This is the **head** of the chain: adding a line here means the next two stages **price it** for you.
$ucidintThe currency the pricing runs in.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.cart_inputs', 10, function (&$inputs, $ucid) {
// The HEAD of the chain: a line added here gets priced by the core.
if (Acme::freeSslCampaign())
$inputs[] = ['group' => 'product', 'product_id' => Acme::SSL_ID, 'cycle' => 'annually'];
});
```
#### Changing the priced lines
filterorder.cart_items
`Orders::buildCart()` the second link
Runs after the lines were priced, before the summary is built.
Parameters 4
$itemsarrayrefThe priced lines: type, product or extension, unit price, total, taxable amount, add-ons, reseller discount. You can change a line total, and yet the **grand total** is worked out again in the next stage.
$user_idintThe order's owner.
$user_currencyintThe order currency.
$dealershiparrayThe customer's reseller settings, resolved.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.cart_items', 10,
function (&$items, $user_id, $user_currency, $dealership) {
// Change a line price here; the GRAND total is built in the next stage.
foreach ($items as &$i)
if (Acme::bundleEligible($i)) $i['price'] = Acme::bundlePrice($i);
});
```
#### Changing the cart summary
filterorder.cart_totals
`Orders::buildCart()` the last link
Runs after the price summary was built — the **final** figures the customer sees are here.
Parameters 5
$summaryarrayrefThe price summary: the subtotal, the display subtotal, the reseller discount, the coupon discount, tax. The **end** of the chain: these figures reach the customer and the invoice.
$itemsarrayThe priced lines as the previous filter left them. Context you cannot change.
$subtotalfloatThe subtotal before discounts and tax.
$selectedCouponsarrayThe coupons in play. Fixed amounts are **already converted** into the customer's currency.
$ctxarrayThe pricing context: currency, taxation type, tax rates, exemption.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.cart_totals', 10,
function (&$summary, $items, $subtotal, $selectedCoupons, $ctx) {
// The END of the chain: what you write here is what the customer sees.
if (Acme::minimumOrder() > (float) $summary['subtotal'])
$summary['acme_notice'] = Acme::minimumNotice();
});
```
#### Stopping the checkout step
gateorder.checkout
`ClientCheckout` the lines are unpriced
Runs before the order is placed. **A guest never reaches here**: the sign-in check runs earlier.
Parameters 2
$memberarrayThe signed-in member's record.
$cartItemsarrayThe raw cart lines. **Not priced yet**: for a rule that depends on an amount, work the prices out yourself or use the summary filter.
Return 1
stringA non-empty string **stops** the action; the text is shown to the customer as the error.
Listener PHP
```php
Hook::add('gate:order.checkout', 10, function ($member, $cartItems) {
// The lines are NOT priced yet: keep amount-based rules out of here.
if (Acme::fraudScore((int) ($member['id'] ?? 0)) > 80)
return 'Your order wants a review; our team will be in touch.';
return null;
});
```
#### Learning that an order was placed
actionorder.checkout_completed
`ClientCheckout` the invoice is unpaid
Runs after the order was placed. Its invoice is **unpaid** at this point.
Parameters 4
$order_idintThe id of the placed order.
$invoice_idintThe order's invoice. Unpaid right now; a zero-total order or one settled from the balance closes **after this hook** in the same request.
$pmethodstringThe resolved payment method. On a zero-total order `Free`; on a stored card the real gateway module's name.
$memberarrayThe record of the member who ordered.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.checkout_completed', 10,
function ($order_id, $invoice_id, $pmethod, $member) {
// The invoice is NOT paid yet: leave opening services to the payment hook.
Crm::orderPlaced($order_id, $pmethod, (string) ($member['email'] ?? ''));
});
```
#### Changing the coupon discount
filterorder.coupon_discount
`Orders` the computed discount
Runs after the coupon discount was worked out.
Parameters 1
$discountarrayrefThe computed discount. It feeds the cart summary and runs **before** the summary filter.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.coupon_discount', 10, function (&$discount) {
Acme::capCouponDiscount($discount);
});
```
#### Changing the order number
filterorder.number
`Orders` it has to be unique
Runs after the order number was produced.
Parameters 1
$numberstringrefThe number produced. Changing it, **guarantee uniqueness yourself**: the core does not check what you produced.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.number', 10, function (&$number) {
// Uniqueness is YOURS to keep: a clash breaks the order.
$number = Acme::prefix() . '-' . $number;
});
```
### Pitfalls
> **The wrong link in the chain is quietly overwritten**
>
> Pricing runs in three stages: inputs, lines, summary. Touching the grand total at the line stage is wasted — the summary stage **works it out again**. A line price belongs on the item filter, a final figure on the summary filter, and a new product on the **input filter**.
> **The lines are unpriced at the checkout gate**
>
> The checkout gate hands you the **raw** cart lines: no amounts, discounts or tax yet. Writing "stop orders above this amount" here means reading **a field that is not there**.
> **Placing an order is not paying for it**
>
> On the order-completed hook the invoice is **unpaid**. Opening a service, switching an add-on on or delivering to the customer here means an order that never pays is **delivered anyway**.
> **Change the number and its uniqueness is yours**
>
> The order number filter hands you a number already produced. Once you change it the core **does not check it again**: produce a clashing one and the order record breaks. Adding your own prefix is safe; producing the number from scratch is not.
### Related Articles
- Order Flow Hooks
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
- [Currency and Coupon Hooks](https://dev.wisecp.com/en/currency-and-coupon-hooks)
## Order Status Hooks
https://dev.wisecp.com/en/order-status-hooks
Nine hooks across an order record's life: creation, status changes, configuration, expiry and deletion.
### Overview
An order is the cart's **lasting record**. Its status decides when services open: a waiting order opens nothing, an active one builds the services.
Carts left unpaid drop **on their own** after a while. That flow has a hook of its own and runs from a scheduled task.
### Reference
#### Stopping an order record
gateorder.create
`Orders::create()` before the record
Runs before the order record is written.
Parameters 1
$dataarrayThe order data about to be written: owner, amount, currency, items, taxes, discounts, status, payment method.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:order.create', 10, function ($data) {
if (Acme::blocked((int) ($data['user_id'] ?? 0)))
return 'This account cannot place new orders.';
return null;
});
```
#### Following an order record
actionorder.created
`Orders::create():215` the status can be waiting
Runs after the order row was written. The services behind it are **not built yet**.
Parameters 1
$orderarrayThe order data joined with its new id: owner, amount, currency, items, taxes, discounts, status, payment method, address, notes. The status is usually **waiting**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.created', 10, function ($order) {
// The services are NOT built yet: they open when the status turns active.
Crm::orderRecord((int) ($order['id'] ?? 0), $order);
});
```
#### Stopping an order status change
gateorder.status_change
`Orders::change_status()` whether it reaches the module
Runs before an order status changes.
Parameters 3
$order_idintThe order id. The record does not arrive; read it yourself where you need it.
$statusstringThe target status.
$apply_on_moduleboolWhether the change **reaches the provider module**. Where it is false no service is built and only the record moves.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:order.status_change', 10,
function ($order_id, $status, $apply_on_module) {
// A change that skips the module builds nothing: shape the rule for that.
if ($status === 'active' && $apply_on_module && !Acme::capacityFree())
return 'No new service can open now; capacity is full.';
return null;
});
```
#### Following an order status
actionorder.status_changed
`Orders::change_status()` the old status can be empty
Runs after an order status changed.
Parameters 3
$idintThe order id.
$statusstringThe new status: `waiting`, `inprocess`, `active`, `cancelled`.
$old_statusstringThe previous status. On the first write it arrives as an **empty string**; allow for that when comparing.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.status_changed', 10, function ($id, $status, $old_status) {
// On the first write the old status is EMPTY: a plain comparison misleads.
if ($old_status === '' || $status === $old_status) return;
if ($status === 'active') Crm::orderActivated($id);
});
```
#### Following an order update
actionorder.updated
`AdminOrders` an operator edited it
Runs after an order record was updated.
Parameters 2
$idintThe order id.
$dataarrayThe update data written.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.updated', 10, function ($id, $data) {
Audit::orderEdited((int) $id, array_keys($data));
});
```
#### Catching an abandoned cart
actionorder.expired
`cronjobs/OrderCleanup` a scheduled task
Runs after an unpaid order timed out and was cancelled.
Parameters 3
$order_idintThe id of the cancelled order.
$ordernumstringThe order number the customer sees.
$user_idintThe cart's owner.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.expired', 10, function ($order_id, $ordernum, $user_id) {
// An abandoned cart: the best moment for a win-back.
Retention::abandoned((int) $user_id, $ordernum);
});
```
#### Stopping an order delete
gateorder.delete
`AdminOrders` a list arrives, not one record
Runs before an order is deleted.
Parameters 1
$idsarrayThe ids about to be deleted. An **array** arrives even for one order; do not expect a single id.
Return 1
stringA non-empty string **stops** the action; the text is thrown as the error.
Listener PHP
```php
Hook::add('gate:order.delete', 10, function ($ids) {
// An ARRAY arrives even for a single delete.
foreach ($ids as $id)
if (Acme::hasPaidInvoice((int) $id))
return 'An order with a paid invoice cannot be deleted.';
return null;
});
```
#### Following an order delete
actionorder.deleted
`Orders::delete()` a last snapshot
Runs after an order was deleted.
Parameters 2
$idintThe id of the deleted order.
$orderarrayA snapshot from **before** the delete, with items, taxes, discounts and details **decoded**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.deleted', 10, function ($id, $order) {
// The items arrive decoded: no JSON parsing needed.
Accounting::orderRemoved((int) $id, $order['items'] ?? []);
});
```
#### Changing the order total
filterorder.total
`Orders` the amount on the invoice
Runs after the order totals were worked out.
Parameters 4
$tax_calcarrayrefThe totals: `total`, `tax_amount`, the extra tax details, the display subtotal. `total` is the amount written **permanently** onto the order.
$subtotalfloatThe subtotal before discounts and tax.
$total_discountfloatThe reseller and coupon discounts together.
$itemsarrayThe final cart lines.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.total', 10,
function (&$tax_calc, $subtotal, $total_discount, $items) {
// total is written PERMANENTLY; touching the tax keys shapes the
// invoice lines as well.
if (Acme::roundUp()) $tax_calc['total'] = ceil((float) $tax_calc['total']);
});
```
### Pitfalls
> **An order record is not a service**
>
> On the order-created hook the status is usually **waiting** and the services behind it are **not built**. A listener doing service work finds nothing here; the right moment is the status turning **active**.
> **On the first write the old status is empty**
>
> The previous status on the status event can be an **empty string**: the order is being written for the first time. A listener comparing "it was this, now it is that" gets it wrong there. Handle the empty value **separately**.
> **The delete gate takes a list**
>
> Even for a single order the gate takes an **array**. A listener expecting one id tries to read the array as a number and the rule **never** holds. Always walk it with a loop.
> **A change that skips the module builds nothing**
>
> The third parameter of the status gate says whether the change **reaches the provider module**. Where it is false only the record moves and nothing opens on a server. A rule about capacity, servers or providers **has to read** it.
### Related Articles
- [Cart Hooks](https://dev.wisecp.com/en/cart-hooks)
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
## Order Configuration Hooks
https://dev.wisecp.com/en/order-configuration-hooks
The eight hooks on the screens where a customer makes choices while ordering: configuring, adding a domain, adding an add-on, and provisioning.
### Overview
The configuration screen is where a customer shapes a product to suit them: the domain choice, add-ons, the term, custom fields. The hooks here touch both **the screen** and **whether a choice is allowed**.
The last hook differs: it runs after payment, **immediately before the services are built**. It is the final stop between an order line and a service.
### Reference
#### Stopping a configuration
gateorder.item_configure
`ClientOrder` the choices are gathered
Runs before the configured product is written into the cart, with the choices **already gathered**.
Parameters 3
$productarrayThe product record: id, type, name, add-ons, requirements, subdomains, options.
$cyclestringThe chosen billing cycle, already validated.
$optionsarrayThe gathered configuration, about to become the cart line's options: the domain choice (`none`, `owned`, `register`, `transfer`, `subdomain`), the add-ons, the custom fields. Every choice the customer made is here.
Return 1
stringA non-empty string **stops** the action; the text is shown to the customer as the error.
Listener PHP
```php
Hook::add('gate:order.item_configure', 10, function ($product, $cycle, $options) {
// Every choice sits in $options: check your business rule here.
if (($options['domain']['option'] ?? '') === 'owned'
&& !Acme::domainReachable($options['domain']['name'] ?? ''))
return 'The domain you entered cannot be reached.';
return null;
});
```
#### Changing the configuration screen
filterorder.configure_data
`ClientOrder` the whole page
Runs after the configuration page's data was built.
Parameters 2
$dataarrayrefThe page's **whole** template data: the product, the prices (raw amounts by cycle), the add-ons, the domain options. The prices arrive **unformatted** and are formatted on screen.
$ctxarrayThe context: the raw product record, its type, its id and the `edit` mark. A filled `edit` means the customer is **editing** a cart line rather than adding a new product.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.configure_data', 10, function (&$data, $ctx) {
// A filled edit means they are editing a cart line, not adding a product.
if (!empty($ctx['edit'])) return;
$data['acme_hint'] = Acme::upsellHint((int) ($ctx['id'] ?? 0));
});
```
#### Changing the add-on screen
filterorder.configure_addon_data
`ClientOrder` the context is a copy
Runs after the add-on purchase screen's data was built.
Parameters 2
$dataarrayrefThe page's whole template data. This is **the one** to change.
$ctxarrayrefThe context: the raw add-on record, the service list and the options. The lists are **copies**: passed by reference and yet a change here **never reaches** the screen.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.configure_addon_data', 10, function (&$data, &$ctx) {
// The lists inside $ctx are COPIES: change $data instead.
$data['services'] = Acme::filterServices($data['services'] ?? []);
});
```
#### Stopping a domain going in the cart
gateorder.domain_add
`ClientOrder` the extension is validated
Runs before a domain is written into the cart.
Parameters 2
$tldRowarrayThe extension record: id, name, status, privacy, DNS management, forwarding add-ons. Already confirmed to be on sale.
$itemarrayThe line about to be written: the action (`register` or `transfer`), the full name, its parts, the years. The years is always `1` here; the term changes during configuration.
Return 1
stringA non-empty string **stops** the action; the text is shown to the customer as the error.
Listener PHP
```php
Hook::add('gate:order.domain_add', 10, function ($tldRow, $item) {
// An extra check on transfers; none needed on a registration.
if (($item['action'] ?? '') === 'transfer' && Acme::recentlyRegistered($item['domain'] ?? ''))
return 'A newly registered domain cannot transfer for 60 days.';
return null;
});
```
#### Stopping an add-on going in the cart
gateorder.service_addon_add
`ClientOrder` ownership is validated
Runs before an add-on is attached to a service, with ownership **already confirmed**.
Parameters 3
$servicearrayThe service the add-on attaches to: id, owner, product, type, status, term, due date.
$addonarrayThe add-on definition: id, name, type (`select`, `radio`, `checkbox`, `quantity`), status, properties.
$itemarrayThe line about to be written: the service, the add-on, the option, the quantity and `upgrade_of`. Above zero, `upgrade_of` marks an **upgrade** of an existing add-on rather than a new purchase.
Return 1
stringA non-empty string **stops** the action; the text is shown to the customer as the error.
Listener PHP
```php
Hook::add('gate:order.service_addon_add', 10, function ($service, $addon, $item) {
// Above zero, upgrade_of marks an UPGRADE, not a new purchase.
if ((int) ($item['upgrade_of'] ?? 0) > 0) return null;
if (($service['status'] ?? '') !== 'active')
return 'An add-on wants a live service to attach to.';
return null;
});
```
#### Changing the services about to be built
filterorder.services_items
`Orders::buildServices()` the last stop before provisioning
Runs after payment, **immediately before** services are built from the order lines.
Parameters 2
$ctxarrayrefThe provisioning context: the order, the invoice, the owner, the currency, the status, the payment method, the languages, the time.
$itemsarrayrefThe product and domain lines about to be built. Dropping one here means that service is **never built** — even though the customer paid for it.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:order.services_items', 10, function (&$ctx, &$items) {
// DROPPING a line builds nothing: where the customer paid, make it good by hand.
foreach ($items as &$i)
$i['options']['acme_batch'] = Acme::batchFor((int) ($ctx['order_id'] ?? 0));
});
```
#### Following an affiliate change
actionorder.affiliate_changed
`AdminOrders` zero means removed
Runs after an order's affiliate changed.
Parameters 2
$order_idintThe order id.
$affiliate_idintThe new affiliate. `0` means the affiliate was **removed**, not that a new one arrived.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.affiliate_changed', 10, function ($order_id, $affiliate_id) {
// 0 means the affiliate was REMOVED; the commission may want taking back.
if ($affiliate_id === 0) Acme::revokeCommission((int) $order_id);
});
```
#### Following a service removed from an order
actionorder.service.deleted
`AdminOrders` the order stays
Runs after a service was removed from an order. The order record **stays where it is**.
Parameters 2
$order_idintThe order id.
$service_idintThe id of the removed service.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:order.service.deleted', 10, function ($order_id, $service_id) {
Audit::orderLineRemoved((int) $order_id, (int) $service_id);
});
```
### Pitfalls
> **Dropping a line at provisioning refunds nothing**
>
> The service-building filter runs **after payment completed**. Drop a line and that service is **never built**, while the customer has paid and the invoice stands. To prevent something, do it at **the cart or checkout gate**.
> **On the add-on screen the context is a copy**
>
> The second parameter is passed by reference and the lists inside it are **copies**: a change there never reaches the screen and your listener looks like it **did nothing**. What you mean to change is in **the first parameter**.
> **Adding an add-on can be an upgrade**
>
> Where `upgrade_of` on the add-on line is above zero the customer is **not buying something new** but upgrading what they have. A rule saying "they already have this, block a second" also blocks **the upgrade**.
> **The configuration screen also opens in edit mode**
>
> A filled `edit` in the screen filter's context means the customer is **editing a cart line** rather than adding a product. Showing an upsell or a welcome note in edit mode asks again about **a choice they already made**.
### Related Articles
- [Cart Hooks](https://dev.wisecp.com/en/cart-hooks)
- [Order Status Hooks](https://dev.wisecp.com/en/order-status-hooks)
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
# Hooks / Modules
## Module Installation Hooks
https://dev.wisecp.com/en/module-installation-hooks
The nine hooks over installing, switching on, deleting and queueing modules.
### Overview
A module travels four steps: it is uploaded, switched on, switched off and deleted. Each step has a gate you can stop at in front of it and an event that reports it behind.
Two shapes differ. The switching hooks take a **list**, because the panel allows a multiple selection; the deletion hooks work with one module.
### Reference
#### Stopping a module being switched on
gatemodule.activate
`AdminModules` a list arrives
Runs before one or more modules are switched on. The panel allows a multiple selection, so what arrives is a **list**.
Parameters 2
$groupstringThe module type: mail, text message, payment or product.
$modulesarrayThe keys being switched on in this request. It is an array even for one module; walk all of them.
Return 1
mixed**A filled return blocks it**: either a text or an array carrying a message, both accepted, and the message is shown to the user. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:module.activate', 10, function ($group, $modules) {
// It is an array even when one module was picked.
foreach ($modules as $key)
if (!Acme::licensed($group, $key)) return 'You hold no licence for this module: ' . $key;
return null;
});
```
#### Following modules being switched on
actionmodule.activated
`AdminModules` a list arrives
Runs after the modules are switched on.
Parameters 2
$groupstringThe module type.
$modulesarrayThe keys that were switched on.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.activated', 10, function ($group, $modules) {
foreach ($modules as $key) Acme::onModuleOn($group, $key);
});
```
#### Following modules being switched off
actionmodule.deactivated
`AdminModules` a list arrives
Runs after modules are switched off. A payment or server module taken out of service can leave **live services** behind it.
Parameters 2
$groupstringThe module type.
$modulesarrayThe keys that were switched off.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.deactivated', 10, function ($group, $modules) {
// Live services may still sit behind a module now switched off.
foreach ($modules as $key) Acme::warnOrphans($group, $key);
});
```
#### Stopping a module being deleted
gatemodule.delete
`AdminModules` one module
Runs before a module is deleted along with its files. Unlike switching on, here there is **one** module.
Parameters 2
$typestringThe module type.
$keystringThe module key.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:module.delete', 10, function ($type, $key) {
// Do not let a module go while services still sit on it.
if (Acme::hasLiveServices($type, $key)) return 'Live services still run on this module.';
return null;
});
```
#### Following a module being deleted
actionmodule.deleted
`AdminModules` after deletion
Runs after a module is deleted. Its files are no longer on disk.
Parameters 2
$typestringThe type of the deleted module.
$keystringThe key of the deleted module.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.deleted', 10, function ($type, $key) {
Acme::forgetModule($type, $key);
});
```
#### Stopping an add-on upload
gatemodule.addon_install
`AdminModules` the uploaded file
Runs before an uploaded add-on package is opened. What you hold is the **raw file**, still in the temporary folder.
Parameters 2
$filearrayThe uploaded file: its name, temporary path and size. The file name **comes from the user**: do not trust it as it stands.
$activatedboolWhether it will be switched on right after the install.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:module.addon_install', 10, function ($file, $activated) {
// The name comes from the user: look at the content, not the name.
if (!Acme::signatureValid($file['tmp_name'] ?? '')) return 'The package signature did not verify.';
return null;
});
```
#### Stopping an add-on deletion
gatemodule.addon_delete
`AdminModules` before the write
Runs before an add-on is removed.
Parameters 1
$keystringThe key of the add-on to be removed.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:module.addon_delete', 10, function ($key) {
if (Acme::isRequired($key)) return 'The installation needs this add-on to run.';
return null;
});
```
#### Changing the add-on list
filtermodule.addons_list
`AdminModules` passed by link
Runs once the list on the add-on page is prepared.
Parameters 1
$moduleListarrayby linkThe list in three groups: enabled, disabled and available to buy. Change it without breaking the shape: the template expects all three groups.
Return 1
voidThe return is ignored; you write over the list.
Listener PHP
```php
Hook::add('filter:module.addons_list', 10, function (&$moduleList) {
// Keep the shape of the three groups.
$moduleList['premium'] = Acme::filterOffers($moduleList['premium'] ?? []);
});
```
#### Stopping an intervention in the queue
gatemodule.queue_intervene
`AdminModules` zero on a bulk action
Runs before an administrator steps into the module queue by hand: retrying, deleting, clearing and running now.
Parameters 2
$actionstringWhat kind of intervention it is.
$idintThe id of the target record. On a **bulk action it arrives as zero**: a rule written to inspect one record then inspects nothing.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:module.queue_intervene', 10, function ($action, $id) {
// On a bulk action the id is ZERO: build no single-record assumption.
if ($id === 0 && $action === 'delete') return 'Bulk deletion is closed.';
return null;
});
```
### Pitfalls
> **The switching hooks receive a list**
>
> Even for a single module the parameter is an **array**. A check that compares it directly catches nothing; walk the list.
> **A bulk queue action carries a zero**
>
> When several records are handled at once the record id arrives as **zero**. A rule written to inspect one record then quietly inspects nothing.
### Related Articles
- Module Hooks
- [System Event Hooks](https://dev.wisecp.com/en/system-event-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Module Settings and Data Hooks
https://dev.wisecp.com/en/module-settings-hooks
The nine hooks over module settings, the API record, tool data and imports.
### Overview
Module settings are saved from four separate places: the module’s own settings, add-on settings, the settings on a page the module opened, and fraud check settings. Each raises its own event.
Beside them sit three filters over data: tool data, the import archive and the transferable types. And one record fires after every outside call.
### Reference
#### Following module settings being saved
actionmodule.config_saved
`AdminModules` after the write
Runs after the settings of a module are saved.
Parameters 2
$typestringThe module type.
$keystringThe module key.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.config_saved', 10, function ($type, $key) {
Acme::invalidateModuleCache($type, $key);
});
```
#### Following add-on settings being saved
actionmodule.addon_settings_saved
`AddonModule` carries secrets
Runs after the settings of an add-on are saved.
Parameters 2
$namestringThe key of the add-on.
$configarrayThe whole configuration written to disk. It holds API keys and access settings: keep it out of your own records and your logs.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.addon_settings_saved', 10, function ($name, $config) {
// Do not carry the configuration itself.
Acme::notifyOps('add-on settings changed: ' . $name);
});
```
#### Following module area settings being saved
actionmodule.area_settings_saved
`AdminArea` only what was sent
Runs after settings on the module’s own management page are saved.
Parameters 3
$module_typestringThe module type.
$module_namestringThe module name.
$valuesarrayThe saved values. Only **what this call sent** is here, not the full settings. Do not read a missing key as "removed".
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.area_settings_saved', 10,
function ($module_type, $module_name, $values) {
// The array holds what was SENT, not the whole settings.
Acme::auditChange($module_name, array_keys($values));
});
```
#### Following fraud module settings
actionmodule.fraud_settings_saved
`FraudModule` carries secrets
Runs after the settings of a fraud check module are saved.
Parameters 2
$namestringThe module key.
$configarrayThe configuration written: its status and settings. It holds a service key; do not carry it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.fraud_settings_saved', 10, function ($name, $config) {
Acme::notifyOps('fraud check settings changed: ' . $name);
});
```
#### Following a module API record
actionmodule.api_logged
`ModuleBase` raw request and response
Runs after a module talks to an outside service. It fires for **every** call, so this is a busy path.
Parameters 4
$typestringThe module type.
$modulestringThe module name.
$actionstringThe operation recorded.
$log_dataarrayThe whole record: the request sent, the response received and the request details. ? It holds **server passwords, API keys and customer data** in the clear. Pick out what you actually need before copying it anywhere.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:module.api_logged', 10, function ($type, $module, $action, $log_data) {
// Do NOT copy the whole record: it carries secrets.
Acme::metric($type . '.' . $module . '.' . $action);
});
```
#### Changing tool data
filtermodule.tool_data
`ServerModule` passed by link
Runs after a server tool returns its data and before it reaches the screen: mailboxes, databases and their siblings.
Parameters 3
$toolstringThe tool key.
$actionstringThe tool operation; the default is the list view.
$dataarrayby linkThe data returned by the module, already normalised.
Return 1
voidThe return is ignored; you write over the data. The hook fires for every tool: check which one you are in first.
Listener PHP
```php
Hook::add('filter:module.tool_data', 10, function ($tool, $action, &$data) {
// The hook fires for every tool.
if ($tool !== 'databases') return;
$data = Acme::hideSystemDatabases($data);
});
```
#### Stopping an import
gatemodule.import_run
`Imports` the reset mode
Runs before a transfer from another system begins. One of the modes **wipes the existing data**, which makes a check here worth the most.
Parameters 3
$platformstringThe source platform.
$typestringThe type of data to transfer.
$import_typestringThe mode: `clean` **wipes** what is there, `enrich` adds to it.
Return 1
string|null**A non-empty text blocks the operation** and is shown as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:module.import_run', 10, function ($platform, $type, $import_type) {
// 'clean' WIPES what is there: close it on live data.
if ($import_type === 'clean' && Acme::hasLiveData($type))
return 'A wiping import cannot run over live data.';
return null;
});
```
#### Changing which archive is opened
filtermodule.import_archive
`AdminModules` passed by link
Runs before an uploaded module archive is opened. Change the path and **a different file** is opened.
Parameters 2
$theFilestringby linkThe full path of the archive in the temporary folder. What you write over it is what gets opened.
$groupstringThe target module type.
Return 1
voidThe return is ignored; you write over the path. If you put a file of your own here, make sure the path is under your control.
Listener PHP
```php
Hook::add('filter:module.import_archive', 10, function (&$theFile, $group) {
// Changing the path opens ANOTHER file: hand over one you built.
$theFile = Acme::repackage($theFile, $group);
});
```
#### Changing which data types can transfer
filtermodule.import_data_types
`Imports` passed by link
Runs while the import wizard asks which data types it should offer.
Parameters 2
$data_typesarrayby linkThe type list; each carries a name, a description and whether it is required.
$platformstringThe active platform.
Return 1
voidThe return is ignored; you write over the list. Dropping a type marked required can start the transfer with data missing.
Listener PHP
```php
Hook::add('filter:module.import_data_types', 10, function (&$data_types, $platform) {
// Dropping a required type starts the transfer short.
$data_types['acme-notes'] = [
'name' => 'Acme notes',
'description' => 'Notes attached to customer records',
'required' => false,
];
});
```
### Pitfalls
> **The API record carries raw secrets**
>
> The record holds the request sent to the outside service and the response as they were: **server passwords, API keys, customer data**. Copying that array into your own store spreads those secrets to a second place. Pick the field you need; do not carry the whole thing.
> **A wiping import cannot be undone**
>
> One import mode **deletes** the data already there. The import gate is the only place you can keep that mode away from live data.
### Related Articles
- Module Hooks
- [System Event Hooks](https://dev.wisecp.com/en/system-event-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
# Hooks / Scheduled Tasks
## Cron Tick Hooks
https://dev.wisecp.com/en/cron-tick-hooks
The hooks over work nobody is watching: run starts, task registration, the queue, periodic rounds and worker management.
### Overview
Scheduled work runs in a **tick**: the system wakes each minute, takes jobs off the queue, opens **helper workers** where needed, and finishes.
One thing is true of every hook here: **nobody is watching**. An error you throw is shown to no one and output you print reaches no one; the only trace is in the records.
### Reference
#### Registering a scheduled task of your own
registercronjobs
`CronJobQueue` registration is a side effect
Runs while the task registry is gathered. This is where you **register** your own.
Parameters 0
—It takes no parameters. You register by calling `CronJobQueue::register()`, not by returning.
Return 1
voidThe return is ignored; registration happens as a **side effect**.
Listener PHP
```php
Hook::add('register:cronjobs', 10, function () {
// You register with a call, not with a return.
CronJobQueue::register('acme.sync', AcmeSyncHandler::class);
});
```
#### Stopping a tick from running
gatecron.worker.run
`cron.php` the run environment
Runs before a tick starts. Stopping it means **no job is processed** in that tick.
Parameters 2
$isCliboolWhether it runs from the command line. False means it was triggered over a request.
$sapistringThe name of the interface running it. Read this where you want it to run in one environment only.
Return 1
stringA non-empty string **blocks** the tick; the text comes back as the reason. No error is thrown and the tick is quietly skipped.
Listener PHP
```php
Hook::add('gate:cron.worker.run', 10, function ($isCli, $sapi) {
// No task runs inside a maintenance window.
if (Acme::maintenanceWindow()) return 'maintenance window';
return null;
});
```
#### Following a tick starting
actioncron.tick.started
`cron.php` it can be a helper
Runs where a tick starts.
Parameters 3
$workerIdstringThis tick's unique worker id. Several ticks can run at once; keep your records apart by this id.
$isChildboolWhether this is a **helper worker**. True means it is not the main tick but a helper opened under load; both run this hook.
$startTsintThe time the tick started.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.tick.started', 10, function ($workerId, $isChild, $startTs) {
// Helper workers run this hook too: tell the two apart.
if ($isChild) return;
Ops::heartbeat($workerId, $startTs);
});
```
#### Following a tick finishing
actioncron.tick.completed
`cron.php` it can be partial
Runs after a tick finished.
Parameters 2
$payloadarrayThe tick summary: `status` (`ok` or `partial`), the worker id, how many jobs ran, the duration, the errors, plus scheduler and helper details. `partial` means the tick **did not finish** its work.
$isChildboolWhether this was a helper worker.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.tick.completed', 10, function ($payload, $isChild) {
// partial means the tick ran out of room; a run of them is a capacity problem.
if (($payload['status'] ?? '') === 'partial')
Ops::warn('cron-partial', (int) ($payload['processed'] ?? 0));
});
```
#### Following a processed job
actioncron.job.processed
`CronJobQueue` once per job
Runs after a queued job was processed.
Parameters 2
$jobarrayThe processed queue row: id, type, payload, attempts. An attempt count above one means the job **failed before**.
$workerIdstringThe id of the worker that ran it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.job.processed', 10, function ($job, $workerId) {
// An attempt count above one means this job failed before.
if ((int) ($job['attempts'] ?? 0) > 1)
Ops::note('cron-retry', $job['type'] ?? '', (int) $job['attempts']);
});
```
#### Joining the daily work
actioncron.day.run
`cronjobs/Daily` your return is recorded
Runs in the daily task round. Unlike the other hooks **your return is recorded**.
Parameters 0
—It takes no parameters.
Return 1
bool|arrayYour return is **gathered and shown in the panel** as success, duration and errors. A wrong return breaks nothing; it only makes your entry look bad.
Listener PHP
```php
Hook::add('action:cron.day.run', 10, function () {
// Your return shows in the panel: true on success, a note otherwise.
$done = Acme::nightlyReport();
return $done ? true : ['status' => false, 'message' => 'the report failed'];
});
```
#### Joining the hourly work
actioncron.hour.run
`cronjobs/HourlyExecute` your return is recorded
Runs once an hour. Attach hourly work here instead of opening a task file: cache clearing, summaries, outside syncing.
Parameters 0
—It takes no parameters.
Return 1
bool|arrayYour return is **gathered and shown in the panel** as success, duration and errors. A wrong return breaks nothing; it only makes your entry look bad.
Listener PHP
```php
Hook::add('action:cron.hour.run', 10, function () {
$n = Acme::syncPartnerCatalog();
return ['status' => true, 'message' => $n . ' records synced'];
});
```
#### Joining the per-minute work
actioncron.minute.run
`cronjobs/PerMinuteExecute` your return is recorded
Runs every minute, the tightest of the rounds. It suits queue draining, outside polling and health checks.
Parameters 0
—It takes no parameters.
Return 1
bool|arrayYour return is gathered and shown in the panel. Time spent here is paid again every minute: if your work is long, hand it to the queue instead of finishing it here.
Listener PHP
```php
Hook::add('action:cron.minute.run', 10, function () {
// Keep it short: this block runs every minute.
$sent = Acme::drainOutbox(50);
return ['status' => true, 'message' => $sent . ' messages sent'];
});
```
#### Joining the monthly work
actioncron.month.run
`cronjobs/MonthlyExecute` your return is recorded
Runs once a month: month-end summaries, reconciliation, archiving.
Parameters 0
—It takes no parameters.
Return 1
bool|arrayYour return is gathered and shown in the panel. Because it runs once a month, a fault can sit unnoticed for weeks; put a clear note in your return.
Listener PHP
```php
Hook::add('action:cron.month.run', 10, function () {
$rows = Acme::archiveLastMonth();
return ['status' => true, 'message' => $rows . ' rows archived'];
});
```
#### Changing how many helpers open
filtercron.spawn.count
`cron.php` server load
Runs after it was decided how many helper workers to open under load.
Parameters 1
$decisionarrayrefThe decision: `count` (how many to open), pending jobs, active workers, the threshold, the ceiling, the reason. The field that acts is **`count`**; the rest explain the decision.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:cron.spawn.count', 10, function (&$decision) {
// Only count acts; open no helpers while the server is under load.
if (Acme::loadHigh()) $decision['count'] = 0;
});
```
#### Changing the chart task list
filtercron.dashboard_chart_tasks
`automation/dashboard` passed by link
Runs while the task picker of the activity chart is being prepared on the automation board. You can add a task type of your own or hide the internal ones.
Parameters 1
$optionsarrayby linkWhat the picker holds: the key is the task name, the value is the title on screen. It is passed by link, so you make your change by writing over the array, **not by returning it**.
Return 1
voidThe return is ignored. Sorting happens before you, so anything you add stays at the end of the list.
Listener PHP
```php
Hook::add('filter:cron.dashboard_chart_tasks', 10, function (&$options) {
// Add a task of your own to the list.
$options['acme-sync'] = 'Acme sync';
// Hide an internal one.
unset($options['queue-cleanup']);
});
```
#### Stopping a run by hand
gatecron.task_run_now
`AdminAutomation` an operator triggers it
Runs before an operator runs a task by hand.
Parameters 2
$taskstringThe key of the task about to run.
$user_idintThe id of the staff member acting.
Return 1
stringA non-empty string **stops** the run; the text is shown to the operator. Triggered from the panel, this hook is one whose message **somebody actually reads**.
Listener PHP
```php
Hook::add('gate:cron.task_run_now', 10, function ($task, $user_id) {
// Triggered from the panel: a person reads your message.
if ($task === 'invoice.generate' && Acme::billingFrozen())
return 'Billing is frozen; this task cannot run now.';
return null;
});
```
#### Following the kill switch
actioncron.kill_switch_toggled
`AdminAutomation` everything stops
Runs where all scheduled work is switched on or off.
Parameters 2
$enabledboolThe new state. Switched off, **no task runs**: no invoices, no suspensions, no renewals.
$user_idintThe staff member who acted.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.kill_switch_toggled', 10, function ($enabled, $user_id) {
// Switching off stops every automation: forgotten, not even invoices go out.
if (!$enabled) Ops::alert('cron-disabled', (int) $user_id);
});
```
### Pitfalls
> **An error thrown here reaches nobody**
>
> On scheduled work hooks **nobody is watching**. An error you throw is shown to neither customer nor operator and only lands in the records. To make a problem known, do it **yourself**: a notification, a record, an alert.
> **Helper workers run the same hooks**
>
> Under load the system opens helper workers and **each one** runs the tick hooks. A notification on "tick started" sends **dozens** in a busy minute. Read the helper mark in the second parameter.
> **One job can be processed more than once**
>
> A failed job is **tried again** and the processed hook runs on each attempt. A listener reacting without reading the attempt count produces a run of records or messages for one job. Check the counter **in your first line**.
> **On the daily hook your return is recorded**
>
> Unlike other event hooks, the periodic ones **gather your return** and show it in the panel as success, duration and errors. Returning nothing leaves your entry blank. Return true on success and **an array with a note** on failure.
### Related Articles
- Scheduled Task Hooks
- [Service Status Hooks](https://dev.wisecp.com/en/service-status-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
## Task Management Hooks
https://dev.wisecp.com/en/task-management-hooks
The eight hooks where an operator reaches into scheduled work by hand: running a task, switching one off, cleaning the queue and the kill switch.
### Overview
Unlike the hooks in the previous article these fire **from the panel**: an operator is there and reads your message.
Two of them weigh heavily. The kill switch turns **every automation** off, and the queue cleanup **deletes history** so you can no longer see what ran when.
### Reference
#### Following a run by hand
actioncron.task_run_now
`AdminAutomation` the job was queued
Runs after an operator triggered a task by hand. The task is **on the queue** at this point, not running yet.
Parameters 2
$taskstringThe name of the task triggered.
$job_idintThe id of the queued job. For the outcome, listen to the queue hook; this one says only that it **joined the queue**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.task_run_now', 10, function ($task, $job_id) {
// The job JOINED the queue and has not run: watch job.processed for the outcome.
Audit::manualRun($task, (int) $job_id);
});
```
#### Following a task switched on or off
actioncron.task_status_changed
`AdminAutomation` a single task
Runs after a single task was switched on or off.
Parameters 2
$taskstringThe name of the task whose status changed.
$enabledboolThe new state. A task switched off **stops quietly** and may go unnoticed.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.task_status_changed', 10, function ($task, $enabled) {
// A task switched off stops quietly: record the critical ones.
if (!$enabled && Acme::criticalTask($task)) Ops::alert('task-off', $task);
});
```
#### Blocking the kill switch
gatecron.kill_switch_disable
`AdminAutomation` it stops everything
Runs before all automation is switched off. This hook fires **on the off direction only**.
Parameters 2
$enabledboolThe target state. On this hook it is **always false**: it fires when switching off, never on.
$pending_countintHow many jobs are waiting. A high number means switching off **holds them all**; weigh that before deciding.
Return 1
stringA non-empty string **stops** the action; the text is shown to the operator as the error.
Listener PHP
```php
Hook::add('gate:cron.kill_switch_disable', 10, function ($enabled, $pending_count) {
// Switching off with many jobs waiting only grows the backlog.
if ($pending_count > 500)
return 'Too many jobs are waiting; let the queue drain first.';
return null;
});
```
#### Stopping a queue cleanup
gatecron.cleanup_run
`AdminAutomation` it deletes history
Runs before the queue history is deleted. The retention days are **separate per status**.
Parameters 3
$completed_daysintRetention days for completed jobs.
$cancelled_daysintRetention days for cancelled jobs.
$failed_daysintRetention days for failed jobs. Keeping this low deletes the **evidence** of a problem.
Return 1
stringA non-empty string **stops** the action; the text is shown to the operator as the error.
Listener PHP
```php
Hook::add('gate:cron.cleanup_run', 10,
function ($completed_days, $cancelled_days, $failed_days) {
// Deleting failures early destroys the evidence of a problem.
if ($failed_days < 30) return 'Failed records want keeping for 30 days.';
return null;
});
```
#### Following what a cleanup removed
actioncron.queue_cleaned
`AdminAutomation` a breakdown by status
Runs after the queue cleanup finished.
Parameters 2
$deletedintHow many records went in total.
$breakdownarrayThe breakdown by status: completed, cancelled, failed. A high failed count means what went was **the trace of a problem**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.queue_cleaned', 10, function ($deleted, $breakdown) {
// Many failed records removed means a problem's trace has gone.
if ((int) ($breakdown['failed'] ?? 0) > 100)
Ops::warn('cron-failures-purged', (int) $breakdown['failed']);
});
```
#### Following a job intervention
actioncron.job_intervened
`AdminAutomation` four separate actions
Runs after an operator reached into a queued job by hand.
Parameters 3
$actionstringThe kind: `retry`, `cancel`, `force_reclaim`, `delete`. The four differ greatly; do not react without reading which.
$queuestringThe queue key: `cron`, `module`, `notification`. There are three queues and all pass this hook.
$idintThe id of the job that was touched.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.job_intervened', 10, function ($action, $queue, $id) {
// force_reclaim takes a stuck job back, which means it runs again.
if ($action === 'force_reclaim') Ops::note('job-reclaimed', $queue, (int) $id);
});
```
#### Catching a return after downtime
actioncron.restore.detected
`cron.php` a long gap
Runs where the system noticed the tasks had not run for a long while.
Parameters 2
$restoreInfoarrayThe gap details: `gap_hours`, `gap_seconds`, `last_seen`. A long gap means the **renewals, suspensions and invoices** of that period are late.
$workerIdstringThe id of the worker that noticed.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:cron.restore.detected', 10, function ($restoreInfo, $workerId) {
// Renewals and suspensions are late across the gap: check the backlog.
Ops::alert('cron-gap', (float) ($restoreInfo['gap_hours'] ?? 0));
});
```
#### Changing the task list
filtercron.task_overview
`AdminAutomation` the panel cards
Runs before the task overview is shown in the panel.
Parameters 1
$tasksarrayrefThe task card rows. Adding your own here **shows it in the list** without running it: use the registration hook for that.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:cron.task_overview', 10, function (&$tasks) {
// Adding to the list does NOT run a task; registration is register:cronjobs.
$tasks = array_filter($tasks, fn ($t) => !Acme::hidden($t['key'] ?? ''));
});
```
### Pitfalls
> **Running by hand is not running**
>
> The manual trigger hook hands you a **queue id**: the job joined the queue and has not run. Waiting for an outcome here is pointless; what the job actually did is told by the **processed hook**.
> **A cleanup cannot be undone**
>
> The cleanup also removes **failed** records, and those are the only trace of a problem. Shortening retention leaves tomorrow's "why did it not run?" **unanswerable**. Guard the failed retention at the gate.
> **The intervention hook carries four different actions**
>
> Retrying, cancelling, reclaiming and deleting pass **one hook** and their outcomes are opposites. A listener written without reading the kind can take a cancelled job for a **restarted** one. There are also three queues; the second parameter says which you are in.
> **Adding to the list does not run a task**
>
> The task list filter changes **what shows in the panel** and nothing more. Your own task does not run for being added there; it wants making known through the **registration hook**. Mixing the two leaves a card that sits in the panel and never runs.
### Related Articles
- [Cron Tick Hooks](https://dev.wisecp.com/en/cron-tick-hooks)
- Scheduled Task Hooks
- [Hooks in the Management Panel](https://dev.wisecp.com/en/hooks-in-the-management-panel)
# Hooks / Content and Notifications
## Notification Hooks
https://dev.wisecp.com/en/notification-hooks
The eight hooks behind every message reaching a customer: the dispatch gate, the recipient list, the variables and delivery.
### Overview
A notification passes **two gates**. The first stops the dispatch itself: it reaches nobody. The second stops **one delivery**: the other recipients still get the message.
Between them sit the recipient list and the variables. The variables filter runs **per recipient**, so one notification can reach each person with different content.
### Reference
#### Stopping the whole dispatch
gatenotification.dispatch
`Notification::dispatch()` a different return contract
Runs before the notification is built. Stopping it means the message reaches **nobody**.
Parameters 3
$groupstringThe notification group: invoice, service, order, domain, tickets.
$namestringThe notification key: `invoice-created`, `welcome` and the like.
$contextarrayThe raw context: the record ids involved, extra parameters, manually added recipients, forced channels.
Return 1
mixed**Any non-empty return** stops the dispatch — even `true`. Unlike the other gates there is **no text requirement** here; returning a value by accident cuts the notification quietly.
Listener PHP
```php
Hook::add('gate:notification.dispatch', 10, function ($group, $name, $context) {
// MIND: ANY non-empty return stops the dispatch, even true.
if ($name === 'invoice-reminder' && Acme::quietHours()) return true;
return null;
});
```
#### Changing the recipient list
filternotification.recipients
`Notification` a row per channel
Runs after the recipients were resolved, before the messages are built.
Parameters 3
$recipientsarrayrefThe recipient rows: channel, account, address, name, cc, language. One person can appear on **several rows**: e-mail and SMS are separate.
$groupstringThe notification group: invoice, service, order, domain, tickets.
$namestringThe notification key: `invoice-created`, `welcome` and the like.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:notification.recipients', 10,
function (&$recipients, $group, $name) {
// One person has SEPARATE rows for e-mail and SMS: filter by channel.
if ($name === 'invoice-created')
$recipients = array_filter($recipients,
fn ($r) => ($r['channel'] ?? '') !== 'sms');
});
```
#### Changing the template variables
filternotification.render_variables
`Notification` runs per recipient
Runs before the message text is produced, **separately for each recipient**.
Parameters 4
$variablesarrayrefThe variable set for this recipient. The placeholders in the template fill from here.
$groupstringThe notification group: invoice, service, order, domain, tickets.
$namestringThe notification key: `invoice-created`, `welcome` and the like.
$recipientarrayThe recipient in hand: channel, language, account, address. The language field matters: produce your text in theirs.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:notification.render_variables', 10,
function (&$variables, $group, $name, $recipient) {
// It runs PER RECIPIENT: produce your text in their language.
$variables['acme_note'] = Acme::note($recipient['lang'] ?? 'en');
});
```
#### Stopping a single delivery
gatenotification.deliver
`Notification` the message is ready
Runs immediately before a built message goes out. Stopping it cuts **this delivery alone**.
Parameters 1
$itemarrayThe item about to be delivered: channel, account, address, name, cc, subject, body, attachments, reason. The text and attachments are **ready**: this is where a last check belongs.
Return 1
stringA non-empty string stops **this delivery**; the other recipients still get theirs.
Listener PHP
```php
Hook::add('gate:notification.deliver', 10, function ($item) {
// It stops THIS delivery alone: the others carry on.
if (Acme::bounced($item['recipient'] ?? '')) return 'the address is dead';
return null;
});
```
#### Following a dispatch
actionnotification.dispatched
`Notification` one array parameter
Runs after the notification went out.
Parameters 1
$payloadarrayA single array: group, name, account, variables, batch id. The batch id ties **every message** of one dispatch together.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:notification.dispatched', 10, function ($payload) {
// The batch id ties every message of one dispatch together.
Acme::trackBatch($payload['batch_id'] ?? '', $payload['name'] ?? '');
});
```
#### Widening the template fields
filternotification.template_merge_fields
`AdminNotifications` the list shown to the operator
Runs while the available fields are listed on the template editing screen.
Parameters 1
$fieldsarrayrefThe field list shown to the operator. Adding one here **shows it in the list**; producing its value wants the variables filter too.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:notification.template_merge_fields', 10, function (&$fields) {
// Adding to the list produces NO value: write the variables filter as well.
$fields['acme_note'] = 'Acme note';
});
```
#### Changing the invoice attachment name
filternotification.invoice_pdf_name
`Notification` the file name
Runs while the invoice document is attached to a notification.
Parameters 1
$namestringrefThe attachment's file name. The name on the customer's machine, so keep to **safe characters**.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:notification.invoice_pdf_name', 10, function (&$name) {
$name = Acme::safeFileName($name);
});
```
#### Changing a template label
filternotification.template_label
`AdminNotifications` it shows in the panel
Runs while a notification template's name in the panel is resolved.
Parameters 1
$labelstringrefThe template's display name. Only the operator sees it; it does not touch the text reaching a customer.
Return 1
voidThe value changes **by reference**; the return is not read.
Listener PHP
```php
Hook::add('filter:notification.template_label', 10, function (&$label) {
$label = Acme::prefixLabel($label);
});
```
#### Changing the invoice lines
filternotification.invoice_items
`Notification::build_items` changes by returning
Runs before the invoice lines reach the template. You can add lines, drop them, reorder them or put a field of your own on each one.
Parameters 3
$resultarrayThe lines prepared for the template. This is what you change.
$invoicearrayThe invoice itself.
$itemsarrayThe raw lines as they came from the database. Use this to recover a field the prepared list dropped.
Return 1
array|nullAn array you return **replaces the whole list**. The trap: with several listeners the last return wins and earlier additions vanish. To add, take the incoming list and build on it.
Listener PHP
```php
Hook::add('filter:notification.invoice_items', 10, function ($result, $invoice, $items) {
// Keep the incoming list: building from scratch erases what others added.
foreach ($result as $i => $line)
$result[$i]['acme_note'] = Acme::noteFor($line['id'] ?? 0);
return $result;
});
```
#### Changing the order lines
filternotification.order_items
`Notification::build_order_items` changes by returning
The same job for order notifications. Lines arrive already split by quantity, with live add-ons loaded.
Parameters 2
$itemsarrayThe lines prepared for the template.
$orderarrayThe order itself, raw line data included.
Return 1
array|nullAn array replaces the whole list; anything else is ignored.
Listener PHP
```php
Hook::add('filter:notification.order_items', 10, function ($items, $order) {
// Hide internal lines from the customer.
return array_values(array_filter($items, fn ($x) => ($x['name'] ?? '') !== 'internal'));
});
```
#### Masking the delivery record
filternotification.log_entry
`LogManager` passed by link personal data
Runs right before an email or SMS record is written to the database. This is where you mask personal data, or keep no record at all.
Parameters 1
$entryarrayby linkThe record about to be written. Shared fields: `channel` (mail or sms), `user_id`, `reason`, `content`, `data`, `private`. Email also carries `subject`.
Return 1
voidThe return is ignored; you change the array in place. Set `$entry['abort'] = true` and **nothing is written**; the counter comes back zero. The message still goes out, only the trace is dropped.
Listener PHP
```php
Hook::add('filter:notification.log_entry', 10, function (&$entry) {
// Never store the body of a password reset.
if (($entry['reason'] ?? '') === 'password-reset') {
$entry['content'] = '[masked]';
return;
}
// Open no record at all for campaign texts.
if (($entry['channel'] ?? '') === 'sms' && ($entry['reason'] ?? '') === 'campaign')
$entry['abort'] = true;
});
```
#### Giving the preview sample values
filternotification.preview_variables
`AdminNotifications` passed by link
Runs while a template is previewed in the panel. The preview sends nothing and knows only the templates that ship with the core, so **fields of a template you added come out empty**. Supply sample values here.
Parameters 2
$variablesarrayby linkWhat the template will receive, name against value. Add your own fields and leave the existing ones alone.
$ctxarrayby linkWhich template is on screen: `group`, `template`, `lang`. Leave without touching anything when it is not yours.
Return 1
voidThe return is ignored; you add values by writing into the array.
Listener PHP
```php
Hook::add('filter:notification.preview_variables', 10, function (&$variables, &$ctx) {
// Care only about your own template.
if (($ctx['template'] ?? '') !== 'acme-welcome') return;
$variables = array_merge($variables, [
'acme_plan' => 'Starter',
'acme_quota' => '10 GB',
]);
});
```
### Pitfalls
> **The dispatch gate reads any return as a block**
>
> The other gates want **a non-empty string**; this one reads **any non-empty value** as a block. Returning something by accident at the end of your closure — even `true` — means the notification **never goes**, with no trace anywhere.
> **One person appears more than once**
>
> The recipient list carries a row **per channel**: a customer on both e-mail and SMS sits on two rows. A listener deduplicating by account id quietly **switches off a whole channel**.
> **The variables filter runs once per recipient**
>
> On a notification reaching ten people this filter runs **ten times**. A query or a remote call inside it turns one notification into ten requests. Prepare the shared data **once** and produce only the per-recipient part inside.
> **Listing a field produces no value**
>
> The template fields filter widens **the list shown to the operator** and nothing else. Add a field without writing the variables filter and the operator puts it in a template, where it reaches the customer **empty**. The two are written together.
### Related Articles
- Knowledge Base and Notification Hooks
- [Customer Account Hooks](https://dev.wisecp.com/en/customer-account-hooks)
- [Invoice Lifecycle Hooks](https://dev.wisecp.com/en/invoice-lifecycle-hooks)
## Knowledge Base Management Hooks
https://dev.wisecp.com/en/knowledge-base-management-hooks
The eight hooks over saving and deleting articles and categories: a gate you can stop at each step, then an event that reports it.
### Overview
The knowledge base is managed from two sides: the **articles** and the **categories** that hold them. Saving and deleting each carry a gate and an event: the gate can stop the write, the event reports it afterwards.
Two distinctions make the work easier. In the save gates **a zero id means a new record**. The delete gates always receive a **list**, even when a single record goes.
### Reference
#### Stopping an article being saved
gateknowledgebase.article.save
`AdminKnowledgebase` before the write
Runs before an article is saved. New records and edits share this gate, and the id tells you which one you have.
Parameters 2
$idintThe id of the article being edited; a **zero on a new record**.
$categoryintThe target category; a zero means the article has none.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:knowledgebase.article.save', 10, function ($id, $category) {
// A zero id means a new record: do not allow one without a category.
if ($id === 0 && $category === 0) return 'A new article needs a category.';
return null;
});
```
#### Following an article being saved
actionknowledgebase.article.saved
`AdminKnowledgebase` after the write
Runs after the article is saved. This is where you refresh your own search index.
Parameters 2
$articlearrayThe freshly saved record: its id, category, status, privacy and rank.
$isNewboolTrue when it was created, false when an existing one was updated.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:knowledgebase.article.saved', 10, function ($article, $isNew) {
Acme::reindex('kb', (int) ($article['id'] ?? 0));
});
```
#### Stopping an article deletion
gateknowledgebase.article.delete
`AdminKnowledgebase` always a list
Runs before articles are deleted. Even when one article goes, what you receive is a **list**.
Parameters 1
$idarrayThe ids about to be deleted. A single deletion still arrives as a one-element array: do not treat it as a number.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:knowledgebase.article.delete', 10, function ($id) {
// It is an array even for a single deletion.
foreach ($id as $one)
if (Acme::isPinned((int) $one)) return 'A pinned article cannot be deleted.';
return null;
});
```
#### Following an article deletion
actionknowledgebase.article.deleted
`AdminKnowledgebase` after deletion
Runs after an article is deleted. Unlike the gate you get **one** article here: with several deleted, the hook fires once per article.
Parameters 2
$iintThe id of the deleted article.
$articlearrayThe snapshot from before deletion, title included. The record is gone: take the title from here if you need it.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:knowledgebase.article.deleted', 10, function ($i, $article) {
// The hook runs per article, so a bulk deletion calls it several times.
Acme::dropFromIndex('kb', $i);
});
```
#### Stopping a category being saved
gateknowledgebase.category.save
`AdminKnowledgebase` before the write
Runs before a category is saved.
Parameters 2
$idintThe id of the category being edited; a zero on a new record.
$parentintThe parent category; a **zero** puts it at the root.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:knowledgebase.category.save', 10, function ($id, $parent) {
// Keep the root level fixed.
if ($parent === 0 && $id === 0) return 'A new category needs a parent.';
return null;
});
```
#### Following a category being saved
actionknowledgebase.category.saved
`AdminKnowledgebase` after the write
Runs after the category is saved.
Parameters 2
$categoryarrayThe fresh category record: id, parent, type, status and rank.
$isNewboolTrue when it was newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:knowledgebase.category.saved', 10, function ($category, $isNew) {
Acme::refreshMenu((int) ($category['id'] ?? 0));
});
```
#### Stopping a category deletion
gateknowledgebase.category.delete
`AdminKnowledgebase` sub-branches included
Runs before categories are deleted. The deletion **reaches down the branches**: sub-categories you do not see in the list go too.
Parameters 1
$idarrayThe ids about to be deleted, an array even for one. Sub-categories are not listed here but **they are deleted too**: write your check to cover the branches below.
Return 1
string|null**A non-empty text blocks the operation** and is shown to the administrator as the error. An empty return lets it carry on.
Listener PHP
```php
Hook::add('gate:knowledgebase.category.delete', 10, function ($id) {
// The branches are not listed but they go as well: walk the tree yourself.
foreach ($id as $one)
if (Acme::branchHasPinned((int) $one)) return 'A pinned article sits in this branch.';
return null;
});
```
#### Following a category deletion
actionknowledgebase.category.deleted
`AdminKnowledgebase` per parent category
Runs after a category is deleted. The hook fires for the **parent**; the branches that went with it do not each get their own call.
Parameters 2
$iintThe id of the deleted parent category.
$categoryarrayThe snapshot from before deletion, title included.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:knowledgebase.category.deleted', 10, function ($i, $category) {
// No separate call arrives for the branches: cover them in your cleanup.
Acme::dropBranchFromIndex($i);
});
```
### Pitfalls
> **The delete gate always receives a list**
>
> Even for a single article the parameter is a **one-element array**. A check that expects a number and compares it directly quietly catches nothing.
> **Category deletion goes down the branch, the hook does not**
>
> Deleting a category takes the whole branch beneath it. The delete event, though, fires only for the **parent**: no separate call arrives for the sub-categories. Write your cleanup to cover the whole tree.
### Related Articles
- Knowledge Base and Notification Hooks
- [Notification Hooks](https://dev.wisecp.com/en/notification-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
## Knowledge Base Display Hooks
https://dev.wisecp.com/en/knowledge-base-display-hooks
The nine hooks over the knowledge base a visitor sees: the body, the tree, the scope, the popular box, search, and four observation points.
### Overview
Everything a visitor sees passes through these hooks: the article body, the category tree, the popular box and the search results. All four are **passed by link**, so you make your change by writing over the incoming value rather than returning it.
Beside them sit four observation hooks: an article read, a category opened, a vote and a search. They change nothing; they report that something happened.
### Reference
#### Following an article being read
actionknowledgebase.article.viewed
`website/knowledgebase` on every opening
Runs when an article is viewed. The visitor may well not be logged in.
Parameters 2
$idintThe id of the article viewed.
$articlearrayThe article data, with the view counter **already increased**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:knowledgebase.article.viewed', 10, function ($id, $article) {
// The visitor may not be logged in: build no assumption about identity.
Acme::trackRead($id);
});
```
#### Following an article vote
actionknowledgebase.article.voted
`website/knowledgebase` one of two values
Runs when a visitor marks an article useful or not.
Parameters 2
$idintThe id of the article voted on.
$typestringWhich way: `useful` or `useless`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:knowledgebase.article.voted', 10, function ($id, $type) {
// Collect the unhelpful votes for the writing team.
if ($type === 'useless') Acme::flagForReview($id);
});
```
#### Following a category being opened
actionknowledgebase.category.viewed
`website/knowledgebase` in the chosen language
Runs when a category page is viewed.
Parameters 2
$catIdintThe id of the category viewed.
$catarrayThe category record **in the chosen language**: title, link and search headings.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:knowledgebase.category.viewed', 10, function ($catId, $cat) {
Acme::trackCategory($catId);
});
```
#### Following a search
actionknowledgebase.searched
`website/knowledgebase` after the filter
Runs when a visitor searches. The result **may be empty**, and searches that find nothing are the best list of articles still to write.
Parameters 3
$querystringThe cleaned search term; it never arrives empty.
$resultsarrayThe final results, **after the filter ran**. An empty array means nothing was found.
$langstringThe language the search ran in.
Return 1
voidThe return is ignored. To change the results use the search results filter, not this hook.
Listener PHP
```php
Hook::add('action:knowledgebase.searched', 10, function ($query, $results, $lang) {
// Searches that find nothing point at the article still to write.
if (!$results) Acme::noteGap($query, $lang);
});
```
#### Changing the article body
filterknowledgebase.article_content
`website/knowledgebase` passed by link
Runs before the article body reaches the screen. Resolve your own shortcodes here, and drop in values like a version number.
Parameters 2
$contentstringby linkThe raw body of the article. What you write over it is the final body.
$ctxarrayby linkContext: the article id, the active language and its category.
Return 1
voidThe return is ignored; you write over the body. The body is raw markup and goes straight to the screen: clean any user data you put into it yourself.
Listener PHP
```php
Hook::add('filter:knowledgebase.article_content', 10, function (&$content, &$ctx) {
// Resolve a shortcode of your own.
$content = str_replace('[version]', Acme::currentVersion(), $content);
});
```
#### Limiting which categories are visible
filterknowledgebase.category_scope
`website/knowledgebase` empty means no limit
Runs while article queries are built. This is how you narrow the knowledge base to an audience: one set for resellers, another for end customers.
Parameters 2
$scopearrayby linkThe category ids the queries will be held to. It **always arrives empty**, and **leaving it empty means no limit**: touch nothing and the whole knowledge base shows.
$ctxarrayby linkContext: which page and which language. It is information only; changing it affects nothing.
Return 1
voidThe return is ignored; you write ids into the list.
Listener PHP
```php
Hook::add('filter:knowledgebase.category_scope', 10, function (&$scope, &$ctx) {
// Leaving it empty means "no limit": fill it to narrow the view.
if (!Acme::isReseller()) $scope = Acme::publicCategories();
});
```
#### Changing the category tree
filterknowledgebase.category_tree
`website/knowledgebase` passed by link
Runs once the category tree beside the content is prepared.
Parameters 2
$treearrayby linkThe top-level nodes. What you write over them is the final tree.
$ctxarrayby linkContext: which page and which language.
Return 1
voidThe return is ignored; you write over the tree.
Listener PHP
```php
Hook::add('filter:knowledgebase.category_tree', 10, function (&$tree, &$ctx) {
// Hide the internal branch from visitors.
$tree = array_values(array_filter($tree, fn ($n) => ($n['id'] ?? 0) !== Acme::INTERNAL_CAT));
});
```
#### Changing the popular article list
filterknowledgebase.popular_articles
`website/knowledgebase` passed by link
Runs while the popular article box beside the content is filled.
Parameters 2
$articlesarrayby linkThe articles to list: titles, links and view counts.
$ctxarrayby linkContext: which page, which language and **how many were asked for**. Mind that limit when adding: the box does not stretch.
Return 1
voidThe return is ignored; you write over the list.
Listener PHP
```php
Hook::add('filter:knowledgebase.popular_articles', 10, function (&$articles, &$ctx) {
// The limit arrives in the context: the box does not stretch.
array_unshift($articles, Acme::featuredArticle());
$articles = array_slice($articles, 0, (int) ($ctx['limit'] ?? 6));
});
```
#### Changing the search results
filterknowledgebase.search_results
`website/knowledgebase` passed by link
Runs before the search results reach the screen. Add results from a source of your own here, or change the order.
Parameters 2
$resultsarrayby linkThe raw result rows: title, link, category name and view count.
$ctxarrayby linkContext: the search text and the language.
Return 1
voidThe return is ignored; you write over the list. Your change carries into the search event as well: that hook runs **after** you and sees the adjusted list.
Listener PHP
```php
Hook::add('filter:knowledgebase.search_results', 10, function (&$results, &$ctx) {
// Add results from a source of your own.
foreach (Acme::search($ctx['query'] ?? '', $ctx['lang'] ?? '') as $row) $results[] = $row;
});
```
### Pitfalls
> **An empty scope is no limit, not a tight one**
>
> The scope list **always arrives empty**, and leaving it that way means "show the whole knowledge base". Wanting to narrow access and leaving the list empty does the opposite.
> **The body is raw markup**
>
> The article body goes straight to the screen and is not cleaned. If you embed a value from outside, escape it yourself.
### Related Articles
- Knowledge Base and Notification Hooks
- [Notification Hooks](https://dev.wisecp.com/en/notification-hooks)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
# Hooks / Platform
## Platform Infrastructure Hooks
https://dev.wisecp.com/en/platform-infrastructure-hooks
The eight hooks under the request: outgoing calls, accepted addresses, routing, template variables, API addresses and product types.
### Overview
These hooks sit **beneath** a request: before an address resolves, before a template is shown, before a call leaves for the outside. All are hot paths, running on every request.
Two deserve care. The **pre-match** stands ahead of the real pages of the install, so an unproven claim shadows them. And **template variables** is not passed by link: the array you return stands in for all of them.
### Reference
#### Changing an outgoing request
filterhttp.request
`Utility::HttpRequest` passed by link
Runs before the system sends a request outward. **Every** outgoing call passes here: server modules, registrars, payment gateways.
Parameters 1
$optionsarrayby linkThe request settings: address, method, body, headers, timeouts, certificate check. Raising a timeout can slow the whole system: this hook sees every call, not one.
Return 1
voidThe return is ignored; you write over the settings.
Listener PHP
```php
Hook::add('filter:http.request', 10, function (&$options) {
// Touch only your own address: this hook sees EVERY outgoing call.
if (!str_contains($options['url'] ?? '', 'api.acme.test')) return;
$options['headers'][] = 'X-Acme-Tenant: ' . Acme::tenant();
});
```
#### Widening the accepted addresses
filterhttp.trusted_hosts
`Kernel` add, do not reset
Runs while the address of an incoming request is checked. The list arrives holding the address the licence is locked to; you **add** yours.
Parameters 2
$hostsarrayby linkThe accepted addresses. **Do not reset** the list: drop the locked address and the install becomes unreachable at its own address.
$contextarrayby linkInformation: the raw address the request came from and the one the licence is locked to.
Return 1
voidThe return is ignored; you add to the list.
Listener PHP
```php
Hook::add('filter:http.trusted_hosts', 10, function (&$hosts, &$context) {
// Add, do not reset: the locked address must stay in the list.
$hosts[] = 'panel.acme.test';
});
```
#### Registering an address of your own
registerroutes
`Router` through the object
Runs while the address table is built. This is the **right** way to open a page of your own: register the address rather than grabbing it in the match hooks.
Parameters 1
$routerobjectThe router. Being an object, calling a method on it is enough; nothing is registered by returning.
Return 1
voidThe return is ignored. Registration happens as a side effect of the call.
Listener PHP
```php
Hook::add('register:routes', 10, function ($router) {
// Registration happens through the call, not the return.
$router->add('acme-status', 'acme/status', 'AcmeStatusController');
});
```
#### Claiming an address ahead of the patterns
filterrouting.prematch
`Router` ahead of the patterns
Runs as an address starts to resolve, **ahead of the registered patterns**. Answering here means stepping in front of the real pages of the install.
Parameters 2
$urlstringThe address being resolved, with the language prefix already split off.
$routesarrayEvery registered address definition, there to look at.
Return 1
array|nullThe **first** listener returning an array with at least a controller key wins. ? The claim must be proven: answering "this might be mine" shadows the real pages of the install. Return `null` unless **your own record** stands behind it. For a permanent page the right place is the address registration, not this.
Listener PHP
```php
Hook::add('filter:routing.prematch', 10, function ($url, $routes) {
// Claim with proof: return null unless you hold a record for it.
if (!Acme::ownsSlug($url)) return null;
return ['key' => 'acme-page', 'controller' => 'AcmePageController', 'params' => [$url]];
});
```
#### Catching an address nothing matched
filterrouting.match
`Router` when no pattern held
Runs when none of the registered patterns held. Unlike the pre-match, claiming here is safe: there is no real page left to shadow.
Parameters 2
$urlstringThe address that did not resolve.
$routesarrayThe registered address definitions.
Return 1
array|nullThe first listener returning an array with a controller key wins. With no answer the address falls to the not-found flow.
Listener PHP
```php
Hook::add('filter:routing.match', 10, function ($url, $routes) {
// No pattern held this address, so claiming it is safe.
$page = Acme::findVanity($url);
if (!$page) return null;
return ['key' => 'acme-vanity', 'controller' => 'AcmeVanityController', 'params' => [$page]];
});
```
#### Changing the variables a template receives
filtertemplate.variables
`View::render` return the whole array
Runs before a template is shown. This is how you carry one value onto every page.
Parameters 2
$template_pathstringThe full path of the template being drawn; use it to tell which page you are on.
$dataarrayEvery variable about to reach the template.
Return 1
array|null? It is **not passed by link**: the array you return **replaces every variable**, it is not merged. Return an array of your own without building on the incoming one and the whole page loses its data, leaving a blank screen. To add something, add to what arrived and return **all of it**. With several listeners the last return wins.
Listener PHP
```php
Hook::add('filter:template.variables', 10, function ($template_path, $data) {
// ADD to what arrived and return all of it: this replaces, it does not merge.
$data['acme_banner'] = Acme::banner();
return $data;
});
```
#### Opening API addresses of your own
filterapi.routes
`API Kernel` three separate tables
Runs while the API address table is built. This is how a module opens its own endpoints without touching the core.
Parameters 2
$routesarrayby linkThe address table. Each row carries the method, pattern, group, action and access settings. Add, change or remove freely.
$audiencestringby linkWhich table: `admin`, `client` or `module`. The hook fires separately for all three: add without checking and your endpoint lands in every table.
Return 1
voidThe return is ignored; you write over the table.
Listener PHP
```php
Hook::add('filter:api.routes', 10, function (&$routes, &$audience) {
// The hook fires for all three tables: check the branch.
if ($audience !== 'admin') return;
$routes[] = ['GET', 'acme/status', 'Module:Addons/Acme', 'status'];
});
```
#### Introducing a new product type
registerproduct_types
`Products` returns definitions
Runs while the product type list is built. Add your own type to the core list here.
Parameters 0
—It takes no parameters.
Return 1
array|nullYou return a **definition map**; returns are merged into the core list. Each definition carries a title, a description and an icon. Empty returns are ignored.
Listener PHP
```php
Hook::add('register:product_types', 10, function () {
return ['acme-vps' => [
'title' => 'Acme VPS',
'description' => 'A virtual server on Acme',
'icon' => 'bi bi-hdd-rack fs-5',
]];
});
```
### Pitfalls
> **Template variables replace, they do not merge**
>
> This filter is not passed by link. The array you return **stands in for every variable**. Return one of your own without building on what arrived and the page loses its data, leaving a blank screen. The fix: add to the incoming array and return **all of it**.
> **An unproven claim in the pre-match shadows real pages**
>
> The pre-match sits **ahead** of the registered patterns. Answering "this might be mine" makes the real pages of the install unreachable. Match only where your own record stands behind the address; for a permanent page the right place is the address registration.
### Related Articles
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
- [Hook Domains](https://dev.wisecp.com/en/hook-domains)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
## Language and Translation Hooks
https://dev.wisecp.com/en/language-and-translation-hooks
The seven hooks over text: resolving a translation, saving one, sweeping a pack, and adding, removing or configuring a language.
### Overview
Text travels two ways: a key **resolves** and reaches the screen, or a translation **is saved** and reaches the disk. Each end carries a filter.
Beside them sit the events of the pack itself: opening one, deleting one, changing its settings. A new pack is not born empty; it is copied from an existing language.
### Reference
#### Changing a resolved text
filteri18n.translation
`Language::g` passed by link
Runs after a translation key resolves to text. **Every** piece of text in the system passes here: it is a hot path, so keep it light.
Parameters 3
$valuestringby linkThe resolved text. What you write over it is the result.
$keystringThe key that was asked for.
$langstringThe language used to resolve it.
Return 1
voidThe return is ignored; you write over the text. Leave it alone and the original comes back.
Listener PHP
```php
Hook::add('filter:i18n.translation', 10, function (&$value, $key, $lang) {
// Every text passes here: sift on the key first.
if ($key !== 'website/home/title') return;
$value = Acme::brandedTitle($lang);
});
```
#### Adjusting translations before they are saved
filteri18n.translation_save
`AdminLanguages` passed by link
Runs before translations are written to disk. The array you hold **is what gets written**.
Parameters 2
$valuesarrayby linkKey against value. A value may be plain text or an array carrying content and variables: be ready for both.
$idstringThe target language.
Return 1
voidThe return is ignored; you write over the array.
Listener PHP
```php
Hook::add('filter:i18n.translation_save', 10, function (&$values, $id) {
// A value may be plain text or an array.
foreach ($values as $k => $v)
if (is_string($v)) $values[$k] = trim($v);
});
```
#### Following a translation being saved
actioni18n.translation_saved
`AdminLanguages` only what truly changed
Runs after a translation key is saved.
Parameters 2
$keystringThe full key that was saved.
$savedarrayThe languages **actually written to disk**. Languages sent but unchanged are **absent** from this list: it does not answer "which languages were submitted".
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:i18n.translation_saved', 10, function ($key, $saved) {
// The list holds what CHANGED, not what was submitted.
foreach ($saved as $lang) Acme::invalidateCache($lang, $key);
});
```
#### Following a bulk replacement
actioni18n.bulk_replaced
`AdminLanguages` one language pack
Runs after a word is replaced throughout one language pack.
Parameters 4
$langstringThe **single** language the sweep ran on.
$wordstringThe raw word searched for; it is not a pattern.
$replacementstringThe text written in its place. It is **not read** as a back-reference: what it holds is written literally.
$changedintHow many keys **actually changed**, not how many were selected.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:i18n.bulk_replaced', 10, function ($lang, $word, $replacement, $changed) {
// The counter holds what changed, not what was selected.
Acme::auditSweep($lang, $word, $changed);
});
```
#### Following a language being added
actionlanguage.added
`AdminLanguages` opened as a copy
Runs after a new language pack is opened. The pack does not start empty: it is built as a **copy** of an existing one.
Parameters 2
$keystringThe key of the new language.
$copied_fromstringThe language the content was copied from. The new pack starts full of the source texts: it does not look "untranslated", it looks **wrong-languaged**.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:language.added', 10, function ($key, $copied_from) {
// The pack starts full of the source texts: put it in the translation queue.
Acme::queueTranslation($key, $copied_from);
});
```
#### Following a language being deleted
actionlanguage.deleted
`AdminLanguages` after deletion
Runs after a language pack is deleted.
Parameters 1
$keystringThe key of the deleted language.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:language.deleted', 10, function ($key) {
Acme::dropTranslations($key);
});
```
#### Following language settings changing
actionlanguage.settings_updated
`AdminLanguages` after the write
Runs after the settings of a language are saved.
Parameters 2
$idstringThe key of the language updated.
$packagearrayThe settings written: display name, rank, whether it reads right to left, and status.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:language.settings_updated', 10, function ($id, $package) {
Acme::syncLocale($id, $package);
});
```
### Pitfalls
> **The translation filter is a hot path**
>
> **Every** piece of text passes through it, hundreds of times on a single page. Sift on the key before doing anything heavy, and leave straight away for calls you do not care about.
> **The saved list is not the submitted list**
>
> The list carried by the translation save event holds **only the languages whose value actually changed**. Languages submitted unchanged are absent, so do not answer "which languages were sent" from it.
### Related Articles
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
- [Hook Domains](https://dev.wisecp.com/en/hook-domains)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
## System Event Hooks
https://dev.wisecp.com/en/system-event-hooks
The ten hooks over the installation itself: add-ons, announcements, imports, tasks, versions, the site map and certificates.
### Overview
These hooks watch **the installation itself** rather than a customer: which add-on was installed, which announcement went out, which transfer finished, whether a new version appeared.
Three of them face outward: the site map towards search engines, the certificate sweep towards your alerting, and the transfer page towards the parties looking at it.
### Reference
#### Following an add-on being installed
actionaddon.installed
`AdminModules` after install
Runs after an add-on package is installed. Being installed does not mean it is switched on.
Parameters 2
$modulestringThe key of the installed add-on.
$activatedboolWhether it was **switched on** during the install. A false means it sits on disk but does not run.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:addon.installed', 10, function ($module, $activated) {
// Installed does not mean switched on.
if ($activated) Acme::onEnabled($module);
});
```
#### Following an add-on status change
actionaddon.status_changed
`AdminModules` one of two values
Runs when an add-on is switched on or off.
Parameters 2
$keystringThe key of the add-on.
$statusstringThe new state: `enable` or `disable`.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:addon.status_changed', 10, function ($key, $status) {
if ($status === 'disable') Acme::pauseIntegration($key);
});
```
#### Following an add-on being deleted
actionaddon.deleted
`AdminModules` after deletion
Runs after an add-on is removed.
Parameters 1
$modulestringThe key of the removed add-on.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:addon.deleted', 10, function ($module) {
Acme::cleanupIntegration($module);
});
```
#### Following an announcement being saved
actionannouncement.saved
`AdminAnnouncements` create and edit
Runs after an announcement is saved.
Parameters 3
$savedIdintThe id of the announcement.
$dataarrayThe saved data: title, message, type, target country and language, product group, server, date range and status.
$isNewboolTrue when newly added, false when updated.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:announcement.saved', 10, function ($savedId, $data, $isNew) {
// Carry only a new announcement to the outside channel.
if ($isNew) Acme::broadcast($data['title'] ?? '', $data['message'] ?? '');
});
```
#### Following an import finishing
actionimport.completed
`Imports` per data type
Runs when a transfer from another system finishes. It fires **per data type**: customers, products and invoices each finish separately.
Parameters 3
$platformstringThe platform data came from.
$typestringThe type of data transferred.
$resultarrayWhat the transfer produced: progress, counters and status.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:import.completed', 10, function ($platform, $type, $result) {
// It fires per type: this does not mean "everything is done".
Acme::noteImport($platform, $type, $result);
});
```
#### Following a task being saved
actiontask.saved
`AdminTasks` create and edit
Runs when a task inside the panel is saved.
Parameters 2
$idintThe id of the task.
$is_newboolTrue when it was newly created.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:task.saved', 10, function ($id, $is_new) {
if ($is_new) Acme::mirrorTask($id);
});
```
#### Following a new version being spotted
actionupdates.new_version_detected
`Updates` notice only
Runs when a new core version is spotted. **Nothing is upgraded**: this is only news.
Parameters 2
$responsearrayWhat the new version carries: its number, type and change list.
$current_versionstringThe version currently installed.
Return 1
voidThe return is ignored.
Listener PHP
```php
Hook::add('action:updates.new_version_detected', 10, function ($response, $current_version) {
// Nothing is upgraded here, it is only reported.
Acme::notifyOps('new version: ' . ($response['version'] ?? '?'));
});
```
#### Adding addresses to the site map
filtersitemap.links
`Sitemap` per language
Runs while the site map is produced. Announce your own pages to search engines here.
Parameters 2
$linksarrayby linkThe list of full addresses. Add or remove freely. Empty entries and repeats are cleaned as the output is made; the order holds.
$ctxarrayby linkContext: the language of this map and the address keys the **active theme does not serve**. The hook runs once per language: build your address for that language.
Return 1
voidThe return is ignored; you add to the list.
Listener PHP
```php
Hook::add('filter:sitemap.links', 10, function (&$links, &$ctx) {
// The hook runs once per language.
foreach (Acme::publicPages($ctx['lang'] ?? '') as $url) $links[] = $url;
});
```
#### Reporting certificates about to expire
filterssl.expiring_services
`cronjobs` returns a contribution
Runs while certificates nearing their end are collected. Add certificates the core does not know about here.
Parameters 1
$maxDaysintThe warning window: how many days ahead to report.
Return 1
array|nullYou return your own **contribution**: the services nearing their end, each with the days left. The core merges every return, so give your share rather than the whole list.
Listener PHP
```php
Hook::add('filter:ssl.expiring_services', 10, function ($maxDays) {
// Return only YOUR share: the core merges them all.
return Acme::expiringCerts($maxDays);
});
```
#### Enriching the transfer verification page
filterlicense.transfer.verify_context
`LicenseTransfer` passed by link
Runs while the licence transfer verification page is shown. Add information of your own here.
Parameters 1
$ctxarrayby linkThe page context: the transfer state and record, the service, and the parties handing over and receiving.
Return 1
voidThe return is ignored; you write over the context.
Listener PHP
```php
Hook::add('filter:license.transfer.verify_context', 10, function (&$ctx) {
$ctx['acme_note'] = Acme::transferNote((int) ($ctx['transfer']['id'] ?? 0));
});
```
### Pitfalls
> **An import finishes per data type**
>
> The import event fires **separately for each type**: customers finish, then products, then invoices. Reading one call as "the whole import is done" starts work on half the data.
> **The certificate hook wants a contribution, not a list**
>
> In the expiry sweep you return your own **share**. The core merges every return, so handing back the whole list duplicates records.
### Related Articles
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
- [Hook Domains](https://dev.wisecp.com/en/hook-domains)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
# API
## The WISECP API
https://dev.wisecp.com/en/the-wisecp-api
What the API is, which surface answers which caller, and the first call you can make against an installation.
### Overview
The API is a second way into the same installation. Everything it exposes is the work the panel already does: creating a client, opening an invoice, provisioning a service, reading a ticket. The difference is who asks. The panel is for a person at a screen; the API is for your code.
It speaks JSON over HTTPS with real HTTP methods and real status codes. A call carries an API key, never a session cookie, so nothing about it depends on someone being logged in.
It is not a mirror of the database. A resource is a business action with its rules attached. A call goes through the same guards the panel does: permissions, validation, hooks, activity records.
### Prerequisites
- The address of an installation you are allowed to integrate with.
- An API key. Which kind depends on the surface you need, and the next article covers both.
- A client that can send a request header. Anything can call this API; the samples use cURL, JavaScript and PHP.
### Structure
There are three surfaces under `/api/v1`, and the segment after the version decides which one answers.
- **/api/v1/admin**: The operator's reach: every client, order, invoice, product and setting in the installation. Backs an internal tool, a migration or a reseller panel of your own.
- **/api/v1/client**: One customer managing their own account. Every call is bounded to the account the key belongs to, so a key can never read a neighbour.
- **/api/v1/
**: Paths a module publishes for itself. The installation ships none of its own here; what answers is whatever the installed modules registered.
The two credentialed surfaces are separate products, not one with a filter over it. A key issued for one is refused on the other, and the address is what tells them apart.
### Example
The health check needs no key, so it is the honest first call. It proves the address is right and the API is reachable, before any credential is in play.
```bash
curl 'https://panel.example.com/api/v1/admin/ping'
# {"data":{"pong":true,"version":"v1","time":"2026-08-06 10:12:41"}}
# with a key, this one reports who the key is and what it may do
curl -H 'Authorization: Bearer wak_...' \
'https://panel.example.com/api/v1/admin/whoami'
```
### Pitfalls
> **Nothing is pushed to you**
>
> There is no webhook delivery. An integration that needs to know when something happened has two options. It can ask again on a schedule, or run its own code inside the installation through a hook. Reacting to Events covers both.
> **v1 is frozen, and that is a promise to you**
>
> New endpoints, new response fields and new optional inputs keep arriving in v1. Removing a field, renaming one or changing a type does not. Neither does turning an optional input into a required one. That work waits for a v2, and an endpoint on the way out carries a `Deprecation` header with at least six months of overlap.
### Related Articles
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [API Resources](https://dev.wisecp.com/en/api-resources)
- [Client API Overview](https://dev.wisecp.com/en/client-api-overview)
- [Reacting to Events](https://dev.wisecp.com/en/reacting-to-events)
## API Authentication and Permissions
https://dev.wisecp.com/en/api-authentication-and-permissions
How a key is issued, how it travels on a request, and how its permissions decide what it may reach.
### Overview
Every credentialed call carries an API key and nothing else. There are no sessions and no cookies, so a call behaves the same from a server, a laptop or a browser tab.
A key holds three things: the surface it belongs to, the list of permissions it was granted, and a request budget per minute. Those three are checked in that order on every request, and the first one that says no ends the call.
The key itself is never stored. What the installation keeps is a hash of it plus the first few characters for display, so a lost key cannot be recovered from the panel. It can only be replaced.
### Prerequisites
- Panel access to issue an admin key, or a customer account to issue a client key.
- A place to store the key that is not your source tree.
### Walkthrough
#### Issue a Key
1. For the admin surface, open **Settings → API Credentials** in the panel and create a credential.
2. For the client surface, the customer creates their own under **API Credentials** in their account, at `/api-credentials`.
3. Copy the key from the confirmation. It is shown once and never again.
#### Grant Permissions
1. Tick the actions the key needs. Each checkbox is one `Group/Action` pair, which is the same name the endpoint documents.
2. Grant the narrowest set that does the job. A key that only reads invoices cannot be turned against your clients.
3. Optionally raise or lower the per-minute budget for that one key; empty means the installation default.
#### Send It and Verify
1. Put the key in an `Authorization: Bearer` header, or in `X-Api-Key` if your client cannot set the first one.
2. Call `whoami` on the surface you issued for. It answers with the key's identity, its permissions and, on the client surface, the account behind it.
3. A `403` here means the key is real but belongs to the other surface. Check the address, not the key.
### Reference
- **wak_ + 32 characters**: Reaches `/api/v1/admin`. Issued by staff, scoped by permission, not tied to any one customer.
- **wck_ + 32 characters**: Reaches `/api/v1/client`. Bound to the account that created it; every query it makes is filtered by that account.
- **Clients/GetClients**: One action. The safe default and the one the documentation names on every endpoint.
- **Clients/***: Every action in that group, including ones added by a later version. Convenient, and wider than it looks.
- *****: The whole surface. Reserve it for a key you fully control and can rotate quickly.
The refusals are distinct on purpose, so a failing integration tells you which of the three checks stopped it.
- **401 missing_token**: No key arrived. Usually a header the client dropped, not a permission problem.
- **403 audience_mismatch**: A real key on the wrong surface.
- **403 insufficient_scope**: The key is valid and the endpoint exists, but that action was not granted. The message names the missing permission.
- **429 rate_limited**: The per-minute budget is spent. `Retry-After` says how long to wait.
### Example
```bash
KEY=$(cat ~/.config/wisecp.key)
curl -H "Authorization: Bearer $KEY" \
'https://panel.example.com/api/v1/admin/whoami'
# {"data":{"id":7,"type":"admin","name":"Billing sync","permissions":["Invoices/*","Clients/GetClients"]}}
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/whoami');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('WISECP_API_KEY')],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
$permissions = $body['data']['permissions'] ?? [];
```
### Pitfalls
> **The key is shown once**
>
> Only a hash is kept, so there is no screen that reveals it later and no support request that can retrieve it. If it is lost, regenerate the credential and update whatever was using it. Treat a regeneration as a small outage and plan it.
> **Ignoring a 429 costs more than obeying it**
>
> The budget is a fixed one-minute window: 120 requests for an admin key and 60 for a client key unless the installation says otherwise. A caller that keeps hammering far past its budget is locked out for a while rather than merely refused. Read `X-RateLimit-Remaining` and pause on `Retry-After`.
> **Repeated bad credentials park your address**
>
> Failed authentication is counted per address, and enough failures in a short window earn a temporary block with a `too_many_auth_failures` answer. A retry loop around a wrong key will find this before you do, so fail loudly on `401` instead of retrying.
### Related Articles
- [The WISECP API](https://dev.wisecp.com/en/the-wisecp-api)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [API Resources](https://dev.wisecp.com/en/api-resources)
- [Client API Overview](https://dev.wisecp.com/en/client-api-overview)
## Request and Response Format
https://dev.wisecp.com/en/request-and-response-format
One envelope, one set of status codes and one pagination shape, on every endpoint of every surface.
### Overview
The shape of a call does not change from resource to resource. If you can read one response you can read all of them, and error handling written once keeps working as your integration grows.
Two rules carry most of it. A successful answer puts its payload under `data`, and a failed one puts a machine-readable code under `error`. The HTTP status always agrees with which of the two arrived.
### Reference
#### The Request
Send JSON with a `Content-Type: application/json` header. A form-encoded POST is accepted as well, which helps when a client cannot set the header. Filters, sorting and paging travel in the query string on every method.
- **Authorization: Bearer**: The API key. `X-Api-Key` is the fallback for clients that cannot set this one.
- **Content-Type**: Set it to `application/json` when the body is JSON. Without it the body is read as form fields.
- **Idempotency-Key**: Optional, POST only, 8 to 191 characters. A repeat of the same key returns the stored answer instead of doing the work twice.
- **X-Http-Method-Override**: For callers behind a proxy that allows only GET and POST. The value replaces the method.
#### The Envelope
Success carries `data`, plus `meta` when there is anything to say about the payload. Failure carries `error` with a stable `code`, a human message and, on validation failures, a `details` map naming the fields.
```json
{ "data": { "id": 42, "email": "ada@example.com" } }
{ "data": [ ], "meta": { "total": 318, "page": 2, "limit": 25, "next_page": 3 } }
{ "error": { "code": "validation_failed", "message": "Email is not valid.",
"details": { "email": "invalid_format" } } }
```
Branch on the key, not on the text. `code` is part of the contract and stays put; `message` is written for a human reading a log and may be reworded.
#### Status Codes
- **200 · 201**: Done. Creation answers with 201 and returns the new record.
- **401**: No key, or one the installation does not know. Fix the credential; a retry will not help.
- **403**: The key is known but not allowed here: wrong surface, missing permission, or a write while demo mode is on.
- **404**: No such endpoint, or no such record for this key. On the client surface a record owned by someone else answers the same way.
- **409**: A request with the same `Idempotency-Key` is still running. Wait and retry.
- **413**: The body is past the server upload limit. It never reached the resource, so nothing was saved.
- **422**: The input was understood and refused. `details` names the fields.
- **429**: Too many requests. Honour `Retry-After`.
- **500**: Something failed on the far side. The detail is kept in the operator's log, not in your response.
#### Pagination
List endpoints take `page` and `limit` in the query string. `limit` defaults to 25 and is capped at 100, so asking for more silently gives you 100. Walk pages with `meta.next_page`, which is `0` on the last one.
Offset paging is the v1 contract. Cursor paging exists only where the data is a timeline, such as ticket messages, and those endpoints document their own cursor fields.
#### Response Headers
Every credentialed answer reports the state of your budget, so you can pace yourself without guessing.
- **X-RateLimit-Limit**: Requests allowed in the current one-minute window.
- **X-RateLimit-Remaining**: What is left of it.
- **X-RateLimit-Reset**: Unix time when the window turns over.
- **Idempotency-Replayed**: Present when the answer came from storage rather than fresh work.
### Example
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients' \
-H 'Authorization: Bearer wak_...' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: signup-8f21c0' \
-d '{"name":"Ada","surname":"Lovelace","email":"ada@example.com"}'
# 201 {"data":{"id":91,...}}
# the same call again returns the same body, and does not create a second client
# 201 Idempotency-Replayed: true
```
### Pitfalls
> **Totals live under meta, not at the top**
>
> A list answer keeps its count at `meta.total`. Reading `total` from the root gives you nothing and no error, which reads as an empty result set. The same goes for `page` and `limit`.
> **Demo mode refuses every write**
>
> While an installation is in demo mode, POST, PUT, PATCH and DELETE come back as `403 demo_mode` before any resource is reached. Reads keep working, so a demo stays browsable through the API. An integration that fails only on writes is worth checking against this first.
### Related Articles
- [The WISECP API](https://dev.wisecp.com/en/the-wisecp-api)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
- [API Resources](https://dev.wisecp.com/en/api-resources)
## API Resources
https://dev.wisecp.com/en/api-resources
How the endpoints are grouped, how a name becomes a permission, and how to find the one you need.
### Overview
The API is organised by resource, not by table. A resource is an area of the product: clients, invoices, services, products, tickets. Inside it, an action is one thing you can do.
That pair is the API's whole naming system. `Clients/GetClients` is the route's identity and the permission you tick when issuing a key. It is also the string in a `403` message and the name the documentation uses. Learn one of them and you know the rest.
Actions read as verbs on purpose: `Get`, `Create`, `Update`, `Delete`, `Bulk`. The HTTP method agrees with the verb, so a name and a method never tell you different stories.
### Structure
The admin surface groups its resources into families. You rarely need more than one family for a given integration, which is also the natural boundary for the permissions you grant.
- **system · reference**: Health, key identity, and the lists every other call fills its fields from: currencies, countries, states, cities, languages, billing cycles, statuses.
- **clients · admins · affiliates**: Customer records with their addresses, groups, documents and access, plus staff accounts and the affiliate programme.
- **orders · invoices · financial · services**: The money path end to end: an order becomes an invoice, a paid invoice becomes a service, and a service renews.
- **products · modules**: What you sell and what provisions it: products with their pricing, add-ons and requirements, plus the module registry behind them.
- **tickets · knowledgebase · website**: Departments and ticket traffic, published articles, and the public site's pages and menus.
- **settings · automation · languages · notifications · tools**: The installation's own machinery: configuration, scheduled work, language packs, notification templates and maintenance tools.
The client surface carries a much shorter list, because a customer manages one account rather than an installation. It is covered in its own article.
#### Finding an Endpoint
Work down, not up. Pick the family, open its reference article in this section, and read the action list. Each entry gives the method, the path, the permission name and a working sample in four languages.
If you know the object but not the family, the name usually gives it away. Anything about a customer's own record lives in `clients`. Anything with a price on it lives in `invoices` or `orders`, and anything running on a server lives in `services`.
### Example
Code that already runs inside an installation does not need HTTP, a key or a network round trip. It can call the same resource in process, and gets back the same envelope.
```php
// over HTTP: GET /api/v1/admin/clients?limit=5
// in process, from a module, a cron handler or a hook listener:
$result = \WISECP\Api\Kernel::internal('Clients/GetClients', [], ['limit' => 5]);
$clients = $result['data'] ?? [];
$total = $result['meta']['total'] ?? 0;
// the client surface needs to be told whose account it is acting on
$me = \WISECP\Api\Kernel::internal('client:Account/GetMe', ['owner_id' => 42]);
```
### Pitfalls
> **A resource is not a table**
>
> Creating a client writes several tables, fires hooks and may send a notification. Reading one merges records that are stored apart. Expecting a column-for-field mapping will mislead you; read the action's field list instead of the schema.
> **Installed modules can add groups of their own**
>
> A module may publish endpoints under a group named `Module:{Type}/{Name}`. They appear as their own permission checkboxes and behave like any other endpoint. They belong to that module and travel with it, so an integration that relies on one should say which module it needs.
### Related Articles
- [The WISECP API](https://dev.wisecp.com/en/the-wisecp-api)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [Client API Overview](https://dev.wisecp.com/en/client-api-overview)
## Calling the API In Process
https://dev.wisecp.com/en/calling-the-api-in-process
Code that already runs inside an installation can call any endpoint without HTTP, a key or a network hop.
### Overview
Every endpoint sample in this documentation carries a fourth tab: **PHP (Internal)**. That tab is not a shortcut for the same HTTP request. It is a second entry point into the same resource. It is meant for code living inside the installation: a module, a cron handler, a hook listener, a theme.
The reason to use it is not speed alone. Calling your own installation over HTTP means issuing a key to yourself and spending that key's rate budget. It also depends on the web server being reachable from itself. The in-process call has none of those and returns the exact same envelope. The two are interchangeable at the point where you read the answer.
It is a trusted context by definition. Authentication, permissions, the rate limiter, the abuse guard, idempotency and the request log belong to the HTTP layer. None of them run here. Whatever you pass is executed.
### Reference
#### The Signature
- **Kernel::internal($groupAction, $input = [], $query = []): array**: Static. Returns the same payload an HTTP call would. Success gives `['data' => …, 'meta' => …]` and failure gives `['error' => ['code', 'message', 'details'?]]`. It never throws for an API-level failure and never prints anything.
- **$groupAction**: The endpoint's own name, `Group/Action` — the same string the documentation and the permission checkbox use. Prefix it with `client:` to reach the client surface.
- **$input**: One flat array holding both the path parameters and the body. Keys whose name matches a placeholder in the route pattern are lifted out as path parameters, in pattern order. Everything left over becomes the request body.
- **$query**: The query string, as an array. Filters, sorting, `page` and `limit` go here, not in `$input`.
#### How $input Splits
A route such as `services/{id}/addons` has one placeholder. Passing `['id' => 5, 'name' => 'Backup']` sends `5` as the path parameter and leaves `['name' => 'Backup']` as the body. You never build the URL yourself, which is why a route change does not break your call.
#### The Client Surface
An HTTP call to the client surface takes the account from the key. There is no key here, so the account has to be named: pass `owner_id` in `$input` and prefix the action with `client:`. It is removed from the input before dispatch, so it never reaches the resource as a body field.
Omitting it is refused rather than guessed. The call returns `owner_required` and nothing runs.
#### What Comes Back on Failure
- **endpoint_not_found**: No endpoint answers that `Group/Action` on that surface. A typo lands here, and so does an admin action called with a `client:` prefix.
- **owner_required**: A client call without `owner_id`.
- **validation_failed · not_found · …**: Whatever the resource itself refuses, in the same shape and with the same code as over HTTP.
- **server_error**: An unexpected failure. The detail goes to the error log, not into the returned message, unless the installation is in debug.
### Example
```php
use WISECP\Api\Kernel;
// admin surface, a list with query options
$res = Kernel::internal('Clients/GetClients', [], ['page' => 1, 'limit' => 50, 'status' => 'active']);
if (isset($res['error'])) {
\Logger::warning('client sync failed: ' . $res['error']['code']);
return;
}
foreach ($res['data'] as $client) { /* ... */ }
$more = (int) ($res['meta']['next_page'] ?? 0);
// path parameter + body in one array
$upd = Kernel::internal('Clients/UpdateClient', ['id' => 42, 'company_name' => 'Acme Ltd']);
// client surface: the account is named, not inferred
$me = Kernel::internal('client:Account/GetMe', ['owner_id' => 42]);
```
### Pitfalls
> **No permission is checked here, so check your own**
>
> An HTTP caller is filtered by its key's permissions before a resource is reached. An in-process call is not filtered at all, because the caller is the installation. If your code runs on behalf of a person, decide what that person may do before you call. Never let a request value choose the action or the target account.
> **Module endpoints cannot be reached this way**
>
> The name is split at its first slash, and a module group already contains one: `Module:Addons/AcmeSync`. The split produces the wrong pair and the call answers `endpoint_not_found`. Code inside the installation should call the module's own class or operation directly; the endpoint exists for outside callers.
> **Nothing is written to the request log**
>
> The API log records HTTP traffic. An in-process call leaves no row there, so an integration that mixes both will show only half its activity to the operator. If a background job needs an audit trail, write one of your own.
> **Demo mode does not stop it**
>
> The demo guard refuses writes at the HTTP layer. This path is below it, so a cron handler or a hook listener keeps writing on an installation in demo mode. That is deliberate: the installation's own machinery has to keep running. It is worth remembering when a demo shows data a demo should not have.
### Related Articles
- [API Resources](https://dev.wisecp.com/en/api-resources)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [Reacting to Events](https://dev.wisecp.com/en/reacting-to-events)
- [Client API Overview](https://dev.wisecp.com/en/client-api-overview)
## Reacting to Events
https://dev.wisecp.com/en/reacting-to-events
Nothing is pushed to your integration, so you either ask again or run your own code where the event happens.
### Overview
There is no webhook delivery. That is a deliberate boundary. The installation never holds a queue of your endpoints and never retries against them. It also never leaks work to an address it cannot verify.
Two approaches replace it, and they answer different questions.
- **Ask again**: Call a list endpoint on a schedule and act on what changed. Needs nothing but a key, works from anywhere, and lags by however long your interval is.
- **Be there when it happens**: Register a listener on a hook and your code runs inside the request that caused the event. Immediate and exact, and it requires code installed on the server.
Choose by where your code can live. An integration outside the installation polls. A module, an add-on or a theme shipped with the installation listens.
### Prerequisites
- For the listener route: somewhere to put PHP inside the installation, which in practice means a module of your own.
- The exact name of the hook you want. Names are catalogued, and one that does not exist fails quietly.
### Walkthrough
#### Pick the Hook
1. Find the moment you care about in the hook catalogue, in the Hooks section of this documentation.
2. Read its parameter list and its mechanism. Some hooks report what happened, others let you change a value, and a third kind can refuse an operation outright.
3. Note the argument count. Declaring more arguments than the hook sends drops your listener.
#### Register a Listener
1. Put a `hooks.php` in your module and add the listener there.
2. Keep the body cheap. It runs inside somebody's request, and slow work there is felt by the person waiting.
3. Hand anything slow to a queue, a file or a scheduled task, and let that do the outbound call.
#### Verify It Runs
1. Trigger the event once for real and confirm your side saw it.
2. If nothing happened, look in the error log before touching the code. One message reports a listener that ran and threw. Another reports a listener whose class or method name could not be resolved.
3. Neither message means the hook name itself is wrong, or the listener returned nothing on purpose.
### Example
This listener reacts to a new order and reads it back through the API in the same process. It leaves the outbound call to a queue.
```php
\Hook::add('action:order.created', 10, function (array $order) {
$id = (int) ($order['id'] ?? 0);
if (!$id) return;
// the same resource the HTTP surface exposes, without a key or a round trip
$full = \WISECP\Api\Kernel::internal('Orders/GetOrder', ['id' => $id]);
if (isset($full['error'])) return;
// queue it; do not call your own endpoint from inside someone's checkout
\Acme\Sync::enqueue('order.created', $full['data']);
});
```
- **action:order.created**: Runs after the order row is written and before the confirmation notification. Receives the order payload merged with its new id. The return is ignored, so the early exits in the listener above only end your own code.
- **action:invoice.status_changed**: The counterpart on the money side: fires whenever an invoice moves between states, including into paid. Receives the reloaded invoice, the new status, the previous one and the transition options. The return is ignored.
### Pitfalls
> **A broken listener is skipped, not surfaced**
>
> The engine catches whatever a listener throws, writes it to the error log and moves to the next one. The page it happened on carries on as if nothing was registered. So "my code never runs" and "my code fails every time" look identical from the outside. The log is the only place they differ.
> **A null argument shifts the ones after it**
>
> Arguments are bound by position and a null one is skipped, so the next value slides into its place. A listener that declared two arguments can receive the second value in the first slot with no warning at all. Read the catalogue entry for what is actually sent.
> **Polling has a floor, and it is your rate limit**
>
> A one-second poll spends a key's whole minute budget in one minute. Pick an interval your integration can live with and filter server-side so each call stays small. Stop on a `429` instead of tightening the loop.
### Related Articles
- [The WISECP API](https://dev.wisecp.com/en/the-wisecp-api)
- [API Resources](https://dev.wisecp.com/en/api-resources)
- [How Hooks Work](https://dev.wisecp.com/en/how-hooks-work)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
- [Hook Domains](https://dev.wisecp.com/en/hook-domains)
# API / Admin API
## Reference Data
https://dev.wisecp.com/en/reference-lists
The seven lookup endpoints turning raw numbers and codes into readable labels.
### Overview
The WISECP API returns **raw values**: a status code, a country number, a currency number. An interface has to turn those into something a person reads, and the dictionary for that sits in these seven endpoints.
The split is deliberate. The resource endpoints stay raw because a label shifts with language and time, while the dictionary stands apart because it rarely moves and can be **fetched once and kept**.
Three endpoints form the address chain: country, state and city. The chain runs one way, and each step wants the number from the step before.
### Reference
#### The Currencies
get/api/v1/admin/reference/currencies
`Reference/GetCurrencies` admin
Returns the currencies defined, with their numbers.
Response fields data[] — 4
idintThe currency number. The currency fields on other endpoints carry it.
codestringThe three-letter code.
namestringThe name shown.
is_defaultboolWhether this is the system default.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/reference/currencies' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/reference/currencies', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const byId = Object.fromEntries(data.map((c) => [c.id, c.code]));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/reference/currencies');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The numbers are NOT ISO numerics: they belong to the installation and differ between them.
$rows = Api::Reference()->GetCurrencies()['data'];
$code = array_column($rows, 'code', 'id'); // [4 => 'USD']
```
#### The Countries
get/api/v1/admin/reference/countries
`Reference/GetCountries` admin
Returns the countries with a number, a code and a translated name.
Query 1
langstringThe language the labels come back in. The panel's current language stands in when it is left out.
Response fields data[] — 3
idintThe country number. The country fields on other endpoints carry it.
codestringThe two-letter country code.
namestringThe country name. It is translated into the language asked for.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/reference/countries?lang=en' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/reference/countries?lang=en', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const name = Object.fromEntries(data.map((c) => [c.id, c.name]));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/reference/countries?lang=en');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Other endpoints want the COUNTRY NUMBER and not the two-letter code; build the map here.
$rows = Api::Reference()->GetCountries([], ['lang' => 'en'])['data'];
$idOf = array_column($rows, 'id', 'code'); // ['US' => 840]
```
#### The States
get/api/v1/admin/reference/states
`Reference/GetStates` admin
Returns the states of one country.
Query 1
country_idintreqThe country number.
Response fields data[] — 2
idintThe state number.
namestringThe state name.
Errors 2
country_required422No country number was given.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/reference/states?country_id=840' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/reference/states');
url.searchParams.set('country_id', countryId);
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const { data } = await res.json();
if (! data.length) allowFreeText();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/reference/states?country_id=' . $countryId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// AN EMPTY list is normal: not every country has states, and the address field is free text there.
$states = Api::Reference()->GetStates([], ['country_id' => $countryId])['data'];
$freeText = ! $states;
```
#### The Cities
get/api/v1/admin/reference/cities
`Reference/GetCities` admin
Returns the cities of one state.
Query 1
state_idintreqThe state number.
Response fields data[] — 2
idintThe city number.
namestringThe city name.
Errors 2
state_required422No state number was given.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/reference/cities?state_id=6' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/reference/cities');
url.searchParams.set('state_id', stateId);
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/reference/cities?state_id=' . $stateId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The chain runs one way: a city wants the country FIRST and then the state number.
$states = Api::Reference()->GetStates([], ['country_id' => $countryId])['data'];
$cities = Api::Reference()->GetCities([], ['state_id' => $states[0]['id']])['data'];
```
#### The Languages
get/api/v1/admin/reference/languages
`Reference/GetLanguages` admin
Returns the languages open to clients, in order.
Response fields data[] — 2
codestringThe language key. This is what goes into the language parameter of other endpoints.
namestringThe name shown for the language.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/reference/languages' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/reference/languages', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
renderLanguagePicker(data);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/reference/languages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The OPEN languages alone come back; the language management endpoint shows the closed ones too.
$open = Api::Reference()->GetLanguages()['data'];
$all = Api::Languages()->GetLanguages()['data'];
```
#### The Billing Cycles
get/api/v1/admin/reference/cycles
`Reference/GetCycles` admin
Pairs the billing cycle codes with the labels people read.
Query 1
langstringThe language the labels come back in. The panel's current language stands in when it is left out.
Response fields data[] — 2
codestringThe cycle code. The order and service endpoints use it.
labelstringThe translated label.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/reference/cycles?lang=en' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/reference/cycles?lang=en', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const label = Object.fromEntries(data.map((c) => [c.code, c.label]));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/reference/cycles?lang=en');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list is a LABEL source and not a gate: which cycles a product sells is a separate question.
$labels = array_column(Api::Reference()->GetCycles()['data'], 'label', 'code');
$sold = Api::Products()->GetProduct(['id' => $pid])['data']['prices'] ?? [];
```
#### The Status Codes
get/api/v1/admin/reference/statuses
`Reference/GetStatuses` admin
Pairs the status codes of one kind of record with their labels.
Query 2
entitystringWhich kind you want: `client` or `product`. The client set stands in when it is left out.
langstringThe language the labels come back in. The panel's current language stands in when it is left out.
Response fields data — 2
entitystringThe kind asked for.
statusesobject[] statuses[]The code and label pairs.
valuestringThe status code.
labelstringThe translated label.
Errors 2
entity_invalid422An unknown kind. The answer's detail gives the list supported.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/reference/statuses?entity=client&lang=en' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/reference/statuses?entity=client', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const label = Object.fromEntries(data.statuses.map((s) => [s.value, s.label]));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/reference/statuses?entity=client');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// TWO kinds exist alone: invoice, order and ticket statuses are absent here and sit in their own articles.
$out = Api::Reference()->GetStatuses([], ['entity' => 'client'])['data'];
$map = array_column($out['statuses'], 'label', 'value');
```
### Pitfalls
> **The numbers belong to the installation and are not universal**
>
> A currency number is the installation's own record, and one currency can carry different numbers on two installations. Resolve it from this list rather than writing it into your code. Country numbers follow the same rule: the **code** travels and the number does not.
> **An empty state list is not an error**
>
> Not every country has states, and the state endpoint returns an **empty list** for one that does not. An address form should offer free text there rather than a picker. An interface reading the empty list as a failure blocks address entry for those countries outright.
> **The status list covers two kinds alone**
>
> The status endpoint gives the client and product states. Invoice, order, service and ticket states are **absent**, and their code lists sit in their own articles. Asking for a kind that is unknown gives an error whose detail shows the list supported.
> **The label language comes with the request and not with the key**
>
> With no language parameter the labels come back in the panel's current language. That language can be **hard to predict** for a background job or a report builder. Always name the language when you mean to keep the result.
> **Fetch once, keep it, refresh rarely**
>
> These lists are not meant to be fetched on every request. Country and city data hardly ever move, while currencies and languages shift when a setting does. Fetching once at start-up and holding the result is quicker and spends none of your quota.
### Related Articles
- [Language Packages](https://dev.wisecp.com/en/language-packages)
- [Ticket Reference Lists](https://dev.wisecp.com/en/ticket-reference-lists)
## Health and Key Check
https://dev.wisecp.com/en/health-and-key-check
The two endpoints saying the API is up and what your key can do.
### Overview
These two endpoints answer an integration's first two questions: **is the API up** and **what can this key do**.
The health check wants no credentials and can be called straight from a monitor or a version check. The key check wants a key while wanting **no scope**: every valid key may read its own permissions.
Together they make a diagnostic pair. When the health check passes and the key check fails, the trouble is with the credentials rather than the server.
### Reference
#### The Health Check
get/api/v1/admin/ping
`System/Ping` no key needed
Returns that the API is up, along with the server time.
Response fields data — 3
pongboolWhether the API is up.
versionstringThe API version.
timestringThe server's time. It comes in the server's own time zone.
Errors —
——This endpoint is open to everyone and returns no error.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/ping'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/ping');
const { data } = await res.json();
const drift = Math.abs(Date.parse(data.time) - Date.now());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/ping');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This endpoint WANTS NO KEY: reaching it says nothing about whether your key works.
$up = Api::System()->Ping()['data']['pong'] ?? false;
```
#### What the Key Is
get/api/v1/admin/whoami
`System/Whoami` no scope needed
Returns which key you are using and what it may do.
Response fields data — 4
idintThe key id.
namestringThe name the key was given.
permissionsstring[]The scopes the key carries. Group and action pairs.
last_accessstringWhen it was last used.
Errors 4
missing_token401The authorisation header was not sent.
invalid_token401The key is not valid.
ip_not_allowed403The request came from outside the addresses allowed.
rate_limited429The request limit was passed.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/whoami' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/whoami', {
headers: { Authorization: `Bearer ${apiKey}` },
});
if (res.status === 401) return promptForKey();
const { data } = await res.json();
const canReadInvoices = data.permissions.some((s) => s.startsWith('Invoices/'));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/whoami');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Reading the scopes UP FRONT beats learning them from a 403 on every call.
$me = Api::System()->Whoami()['data'];
$may = fn (string $s) => in_array($s, $me['permissions'], true)
|| in_array(explode('/', $s)[0] . '/*', $me['permissions'], true);
```
### Pitfalls
> **The health check does not verify your key**
>
> The health endpoint checks no credentials: it **answers successfully** even with a key revoked, expired or never sent. Resting a connection test on it alone reports a healthy system while the real calls fail.
> **The server time is not your time**
>
> The time returned sits in the server's own zone and can differ from yours. The dates on the other endpoints share that zone, so comparing one against your own clock gives **results that do not line up**. Take this endpoint's time as the reference.
> **The scope list can carry a wildcard**
>
> The permission list can hold a group wildcard or a star covering everything rather than the actions one by one. Looking for an action with a **plain comparison** gives a false negative on a key that carries a wildcard. Test the group wildcard as well.
> **The quickest way to tell an auth error apart**
>
> When a call answers `403` the cause is either a missing scope or the wrong key. The key endpoint tells the two apart in one call: with it working the key is valid and the trouble lies **in the scope**. A restricted address and a passed request limit show here as well.
### Related Articles
- [Reference Lists](https://dev.wisecp.com/en/reference-lists)
- [API Credentials](https://dev.wisecp.com/en/api-credentials)
# API / Admin API / Administrators
## Staff Accounts
https://dev.wisecp.com/en/staff-accounts
The six endpoints that open, update and remove the staff accounts using the panel.
### Overview
Staff accounts are the people who **can sign into the panel**. They live in a record set apart from clients, yet their e-mail addresses **share one pool** with them.
What an account can do rests on its **privilege group**, and which support tickets it sees on the **departments** it is assigned to. Both are handled at endpoints of their own.
The installation's **founding account** is guarded: it cannot be removed and its privileges cannot change. Your own account is guarded in part as well, since you can neither lower your own privileges nor remove yourself.
### Reference
#### Listing the Staff
get/api/v1/admin/admins
`Admins/GetStaff` admin
Returns the accounts that can sign into the panel.
Query 3
pageintWhich page.
limitintRecords per page. Clamped between one and a hundred.
searchstringSearches the name, e-mail, phone and id.
Response fields data[] — 7 + meta — 4
idintThe staff id.
full_namestringTheir name.
emailstringTheir e-mail address.
statusstringWhether the account is live.
privilege_namestringThe name of the privilege group they belong to.
departmentsstring[]The departments they are assigned to.
is_rootboolWhether it is the installation's founding account. It cannot be removed and its privileges cannot change.
totalintHow many there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/admins' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/admins', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The founding account carries its own mark; leave it out when writing bulk work.
$staff = Api::Admins()->GetStaff()['data'];
$rest = array_filter($staff, fn ($s) => ! $s['is_root']);
```
#### Opening a Staff Account
post/api/v1/admin/admins
`Admins/CreateStaff` admin grants panel access
Opens a new account able to sign into the panel.
Body 15
full_namestringreqTheir name.
emailstringreqTheir e-mail address. Unique across staff and clients alike.
passwordstringreqThe account password.
password_confirmationstringreqThe password again.
privilegeintreqThe privilege group to join. This sets what the account can do in the panel.
langstringreqThe panel language.
display_namestringThe name clients see. Left empty, the real name shows.
phonestringThe phone number. Long enough, it gets formatted and checked for being unique.
departmentsint[]The departments to assign. Left out on an update, the current ones stay.
signatureobject | stringThe reply signature per language.
notesstringA note on the account.
display_modestringThe panel's look preference.
menu_statestringHow the menu opens.
statusstringWhether the account is live. Live by default.
avatarstringThe profile picture.
Response fields 201 — data
dataobjectThe account opened. Same shape as the detail endpoint.
Errors 4
staff_save_failed422The e-mail or phone is taken, the privilege group is not valid, or the passwords differ.
create_failed422The account could not be opened.
blocked_by_gate422A hook refused the account.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/admins' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"full_name":"Ayse Yilmaz","email":"ayse@ornek.com","password":"G1zliParola","password_confirmation":"G1zliParola","privilege":2,"lang":"tr"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/admins', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
full_name: 'John Doe',
email: 'john@example.com',
password: secret,
password_confirmation: secret,
privilege: 2,
lang: 'en',
departments: [1, 2],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'full_name' => 'John Doe',
'email' => 'john@example.com',
'password' => $secret,
'password_confirmation' => $secret,
'privilege' => 2,
'lang' => 'en',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The privilege group decides WHAT THE ACCOUNT CAN DO; do not default to the widest one.
Api::Admins()->CreateStaff([
'full_name' => 'John Doe',
'email' => $email,
'password' => $secret,
'password_confirmation' => $secret,
'privilege' => $limitedGroupId,
'lang' => 'en',
]);
```
#### Reading One Staff Member
get/api/v1/admin/admins/{id}
`Admins/GetStaffMember` admin
Returns one staff account with all of its fields.
Response fields data — 21
idintThe staff id.
statusstringWhether the account is live.
full_namestringTheir name.
namestringTheir first name.
surnamestringTheir last name.
emailstringTheir e-mail address.
phonestringTheir phone number.
langstringThe panel language.
privilege_idintThe privilege group they belong to.
gsm_ccstringTheir mobile country code.
gsmstringTheir mobile number.
residence_addressstringTheir address.
notesstringThe note on the account.
display_modestringTheir look preference.
menu_statestringHow their menu opens.
signatureobject | stringTheir reply signature per language.
has_2faboolWhether the second step of sign-in is on.
authentication_methodsstring[]The names of the verification methods in use. Only the names, and never a secret.
department_idsint[]The departments they are assigned to.
avatar_urlstringThe address of their profile picture.
is_rootboolWhether it is the founding account.
Errors 2
not_found404No such staff member.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/admins/5' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The password NEVER comes back, and on the verification side only method NAMES show.
$s = Api::Admins()->GetStaffMember(['id' => $id])['data'];
```
#### Updating a Staff Member
patch/api/v1/admin/admins/{id}
`Admins/UpdateStaff` admin some fields are guarded
Changes the staff account fields you send.
Body 15
full_namestringTheir name.
emailstringTheir e-mail address.
passwordstringA new password. Send it together with its repeat.
password_confirmationstringThe new password again.
privilegeintThe privilege group. Ignored on the founding account and on your own.
langstringThe panel language.
display_namestringThe name clients see. Left empty, the real name shows.
phonestringThe phone number. Long enough, it gets formatted and checked for being unique.
departmentsint[]The departments to assign. Left out on an update, the current ones stay.
signatureobject | stringThe reply signature per language.
notesstringA note on the account.
display_modestringThe panel's look preference.
menu_statestringHow the menu opens.
statusstringWhether the account is live. Live by default.
avatarstringThe profile picture.
Response fields data — 21
dataobjectThe account as it now stands. Same shape as the detail endpoint.
Errors 3
not_found404No such staff member.
staff_save_failed422The e-mail or phone is taken, the privilege group is not valid, or the passwords differ.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/admins/5' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"full_name":"Ayse Kaya","departments":[1,3]}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ full_name: 'Jane Doe', departments: [1, 3] }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['full_name' => 'Jane Doe', 'departments' => [1, 3]]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A department list REPLACES what was there; leave the field out to keep the current ones.
Api::Admins()->UpdateStaff(['id' => $id, 'full_name' => 'Jane Doe']);
```
#### Removing a Staff Member
delete/api/v1/admin/admins/{id}
`Admins/DeleteStaff` admin
Removes a staff account.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the account removed.
Errors 6
not_found404No such staff member.
root_protected422The founding account cannot go.
self_protected422You cannot remove your own account.
delete_failed422The account could not be removed.
blocked_by_gate422A hook refused the delete.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/admins/6' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// For someone who left, switch the account OFF rather than delete: past work keeps its owner.
Api::Admins()->UpdateStaff(['id' => $id, 'status' => 'passive']);
```
#### Turning Off the Second Step
post/api/v1/admin/admins/{id}/disable-authentication
`Admins/DisableStaffAuthentication` admin the panel asks for a password
Takes away a staff member's second sign-in step.
Body 1
methodstringreqThe verification method to turn off. Its name comes from the list on the staff detail.
Response fields data — 2
disabledboolWhether it was turned off.
methodstringThe method turned off.
Errors 2
not_found404No such staff member.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/admins/5/disable-authentication' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"method":"GoogleAuthenticator"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/${id}/disable-authentication`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ method: 'GoogleAuthenticator' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/' . $id . '/disable-authentication');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['method' => 'GoogleAuthenticator']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// In the panel this asks for the ADMIN PASSWORD; over the API the key's scope is the only gate.
$s = Api::Admins()->GetStaffMember(['id' => $id])['data'];
foreach ($s['authentication_methods'] as $m)
Api::Admins()->DisableStaffAuthentication(['id' => $id, 'method' => $m]);
```
### Pitfalls
> **The e-mail pool is shared with clients**
>
> A staff account's e-mail has to be unique not only among staff but **among clients too**. The same address cannot carry both a client and a staff account. On an installation that also registers its own team as clients, this surfaces as an unexpected clash error.
> **You cannot lower your own privileges**
>
> The update call quietly ignores the privilege and status fields **on the founding account and on your own**. You cannot lock yourself out by accident, yet neither can you assume the value you sent was applied. Read the privilege group in the response and weigh it against what you expected.
> **The department list replaces what was there**
>
> Sending a department list on an update **replaces** what was assigned. Sending only the one you meant to add drops the rest. To keep the current assignments leave the field out entirely, and to add one, read the detail first and merge.
> **Turning off the second step is easier here**
>
> Turning off a staff member's second sign-in step asks for the **administrator password** in the panel, while here the key's scope is the only gate. A key carrying it can strip an account's extra protection outright. Weigh this scope on its own when handing keys out.
> **Switch a departed member off rather than delete**
>
> Deleting a staff member **takes the account away**, while the work they did, the replies they wrote and the notes they left keep pointing at them in the records. Switching the account off stops the sign-in and leaves the history readable. The founding account and your own cannot be removed at all.
### Related Articles
- [Staff Privilege Groups](https://dev.wisecp.com/en/staff-privilege-groups)
- [Staff Departments](https://dev.wisecp.com/en/staff-departments)
- [Ticket Reference Lists](https://dev.wisecp.com/en/ticket-reference-lists)
## Staff Privilege Groups
https://dev.wisecp.com/en/staff-privilege-groups
The six endpoints that set what staff can do in the panel.
### Overview
A privilege group decides what a staff member **can see and can change** in the panel. Every staff member belongs to one group, and what that group carries is what they carry.
The full list of privileges that can be granted comes from an **endpoint of its own**. The catalogue follows the installation: modules installed add their own, and a few depend on the country.
The installation's **founding group** is guarded: it cannot be removed and cannot lose the right to manage privileges. That keeps anyone from leaving themselves unable to grant anything.
### Reference
#### Reading the Privilege Catalogue
get/api/v1/admin/admins/privilege-keys
`Admins/GetPrivilegeKeys` admin
Returns every privilege a group can carry, gathered into groups.
Response fields data[] — 4 + meta
groupstringThe group key.
group_labelstringThe group's readable name. In the panel's current language.
singleboolWhether the group holds one privilege alone. When true the group name and the privilege name say the same thing.
permissionsobject[]The privileges in the group: each with its key and readable name.
totalintHow many groups there are. It comes back under meta.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/admins/privilege-keys' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/admins/privilege-keys', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const keys = data.flatMap((g) => g.permissions.map((p) => p.key));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/privilege-keys');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The catalogue follows the INSTALLATION: modules add privileges, and some depend on country.
$groups = Api::Admins()->GetPrivilegeKeys()['data'];
```
#### Listing the Groups
get/api/v1/admin/admins/privileges
`Admins/GetPrivileges` admin
Returns the privilege groups defined and who sits in them.
Query 3
pageintWhich page.
limitintRecords per page.
searchstringSearches the group name.
Response fields data[] — 5 + meta — 4
idintThe group id.
namestringThe group name.
permission_countintHow many privileges it carries.
appointeesobject[]The staff in this group: their ids and names.
is_rootboolWhether it is the founding group. It cannot be removed.
totalintHow many there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/admins/privileges' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/admins/privileges', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/privileges');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list gives the COUNT rather than the privilege NAMES; read the detail for those.
$groups = Api::Admins()->GetPrivileges()['data'];
```
#### Creating a Group
post/api/v1/admin/admins/privileges
`Admins/CreatePrivilege` admin
Defines a new privilege group.
Body 2
namestringreqThe group name.
permissionsstring[]The privilege keys to grant. Valid keys come from the catalogue endpoint.
Response fields 201 — data — 4
dataobjectThe group created. Same shape as the detail endpoint.
Errors 5
name_required422The group name is empty.
permissions_exceed_holder422The group would grant permissions the account behind your key does not hold. A key owned by the root privilege group is not capped.
create_failed422The group could not be created.
blocked_by_gate422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/admins/privileges' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Destek Ekibi","permissions":["TICKETS"]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/admins/privileges', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Support Team',
permissions: ['ADMIN_CONFIGURE', 'TICKETS'],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/privileges');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Support Team',
'permissions' => ['ADMIN_CONFIGURE', 'TICKETS'],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A group with no privileges is valid: it gets created while its members see nothing.
Api::Admins()->CreatePrivilege([
'name' => 'Support Team',
'permissions' => ['TICKETS'],
]);
```
#### Reading One Group
get/api/v1/admin/admins/privileges/{pid}
`Admins/GetPrivilege` admin
Returns one privilege group with the privileges it carries.
Response fields data — 4
idintThe group id.
namestringThe group name.
permissionsstring[]The privilege keys in the group.
is_rootboolWhether it is the founding group.
Errors 2
not_found404No such privilege group.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/admins/privileges/1' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/privileges/${pid}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/privileges/' . $pid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Read this BEFORE adding a privilege: the write call REPLACES the list rather than adding.
$g = Api::Admins()->GetPrivilege(['pid' => $pid])['data'];
```
#### Updating a Group
patch/api/v1/admin/admins/privileges/{pid}
`Admins/UpdatePrivilege` admin the list replaces
Changes a group's name and the privileges it carries.
Body 2
namestringThe group name.
permissionsstring[]The complete set of privileges. Your list replaces what was there.
Response fields data — 4
dataobjectThe group as it now stands. Same shape as the detail endpoint.
Errors 7
not_found404No such privilege group.
name_required422The group name is empty.
root_needs_privileges422The founding group cannot lose the privilege-management right.
permissions_exceed_holder422The group would grant permissions the account behind your key does not hold. A key owned by the root privilege group is not capped.
save_failed422The group could not be saved.
blocked_by_gate422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/admins/privileges/3' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"permissions":["TICKETS","SERVICES"]}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/privileges/${pid}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
permissions: ['ADMIN_CONFIGURE', 'TICKETS', 'SERVICES'],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/privileges/' . $pid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['permissions' => ['TICKETS', 'SERVICES']]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// To add one privilege, read the CURRENT list and append; otherwise the rest drop away.
$g = Api::Admins()->GetPrivilege(['pid' => $pid])['data'];
$g['permissions'][] = 'SERVICES';
Api::Admins()->UpdatePrivilege(['pid' => $pid, 'permissions' => $g['permissions']]);
```
#### Removing a Group
delete/api/v1/admin/admins/privileges/{pid}
`Admins/DeletePrivilege` admin
Removes a privilege group.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the group removed.
Errors 4
not_found404No such privilege group.
root_protected422The founding group cannot go.
delete_failed422The group could not be removed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/admins/privileges/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/privileges/${pid}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/privileges/' . $pid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Move the STAFF INSIDE first: accounts bound to the group can be left without footing.
$g = current(array_filter(
Api::Admins()->GetPrivileges()['data'], fn ($x) => $x['id'] === $pid,
));
if (! $g['appointees']) Api::Admins()->DeletePrivilege(['pid' => $pid]);
```
### Pitfalls
> **The privilege list is replaced, not added to**
>
> The privilege list you send on an update **replaces** what was there. Sending only the new privilege to widen a group strips every other one from it, and the staff inside suddenly see next to nothing in the panel. Read the detail first and append to it.
> **The catalogue follows the installation**
>
> The list of privilege keys is not fixed: modules installed add their own, and a few depend on the **installation's country**. A script with the keys written into it tries to grant something that does not exist on another installation. Read the catalogue each time.
> **The founding group cannot lose privilege management**
>
> Taking the privilege-management right away from the founding group is **refused**. The lock is deliberate: were that right lost, no account could grant anything again and the installation would be left unmanageable. The group cannot be removed either.
> **Empty a group before removing it**
>
> Removing a privilege group can leave the staff bound to it **without footing**. The listing gives the people in each group by name, so look there and move the accounts to another group first. Removing an empty group is safe.
> **The listing does not name the privileges**
>
> The group listing gives the **number of privileges** alone and not which ones. Two groups can carry the same count and do entirely different things. To see what a group really allows, read it from the detail endpoint.
### Related Articles
- [Staff Accounts](https://dev.wisecp.com/en/staff-accounts)
- [Staff Departments](https://dev.wisecp.com/en/staff-departments)
- [API Credentials](https://dev.wisecp.com/en/api-credentials)
## Staff Departments
https://dev.wisecp.com/en/staff-departments
The six endpoints that set up support departments and assign their staff.
### Overview
Departments decide **which team a support ticket lands with**. A client picks a department when opening one, and the staff assigned there are the people who can take it on.
A department's name and description are kept **per language**. Creating one wants a name in every live language on the installation, while an update changes the ones you send alone.
The icon comes in two forms: a **typeface icon** or an uploaded **image**. A separate endpoint removes the image, and the type falls back to the typeface once it goes.
### Reference
#### Listing the Departments
get/api/v1/admin/admins/departments
`Admins/GetDepartments` admin
Returns the support departments and who handles them.
Query 3
pageintWhich page.
limitintRecords per page.
searchstringSearches the department name.
Response fields data[] — 7 + meta — 4
idintThe department id.
namestringIts name. In the panel's current language.
descriptionstringWhat it is for.
iconstringIts icon.
icon_typestringWhether the icon comes from a typeface or an image.
icon_urlstringThe image icon's address. Filled for an image icon alone.
appointee_idsint[]The ids of the staff handling it.
totalintHow many there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/admins/departments' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/admins/departments', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const orphan = data.filter((d) => d.appointee_ids.length === 0);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/departments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A ticket landing in a department with no staff can be assigned to NOBODY; look for empty lists.
$deps = Api::Admins()->GetDepartments()['data'];
$orphan = array_filter($deps, fn ($d) => ! $d['appointee_ids']);
```
#### Creating a Department
post/api/v1/admin/admins/departments
`Admins/CreateDepartment` admin every language needed
Opens a new support department.
Body 7
namesobjectreqThe department name per language. A name is needed in every live language on the installation.
descriptionsobjectThe description per language.
rankintWhere it sits in the listing.
appointeesint[]The staff handling it. These are the people a ticket can be assigned to.
icon_typestringWhether the icon comes from a typeface or an image. A typeface by default.
iconstringThe typeface icon's class.
icon_imagestringThe icon image to upload.
Response fields 201 — data — 7
dataobjectThe department created. Same shape as the detail endpoint.
Errors 3
name_required422The name is missing in one of the live languages.
create_failed422The department could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/admins/departments' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"names":{"tr":"Genel","en":"General"},"appointees":[1,5]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/admins/departments', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
names: { en: 'General', tr: 'Genel' },
descriptions: { en: 'General questions' },
appointees: [1, 5],
icon_type: 'font',
icon: 'fa-solid fa-globe',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/departments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'names' => ['en' => 'General', 'tr' => 'Genel'],
'appointees' => [1, 5],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Creating wants a name in EVERY live language; an update touches the ones you send alone.
Api::Admins()->CreateDepartment([
'names' => ['en' => 'General', 'tr' => 'Genel'],
'appointees' => [1, 5],
]);
```
#### Reading One Department
get/api/v1/admin/admins/departments/{did}
`Admins/GetDepartment` admin
Returns one department with all of its languages.
Response fields data — 7
idintThe department id.
rankintWhere it sits in the listing.
iconstringIts icon.
icon_typestringWhether the icon comes from a typeface or an image.
icon_urlstringThe image icon's address.
appointee_idsint[]The ids of the staff handling it.
translationsobjectThe name and description per language. Every language comes together.
Errors 2
not_found404No such department.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/admins/departments/4' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/departments/${did}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/departments/' . $did);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list gives ONE language and the detail gives them all; translation work starts here.
$d = Api::Admins()->GetDepartment(['did' => $did])['data'];
$en = $d['translations']['en']['name'] ?? '';
```
#### Updating a Department
patch/api/v1/admin/admins/departments/{did}
`Admins/UpdateDepartment` admin
Changes the department fields and languages you send.
Body 7
namesobjectThe department name per language. Only the languages you send change.
descriptionsobjectThe description per language.
rankintWhere it sits in the listing.
appointeesint[]The staff handling it. These are the people a ticket can be assigned to.
icon_typestringWhether the icon comes from a typeface or an image. A typeface by default.
iconstringThe typeface icon's class.
icon_imagestringThe icon image to upload.
Response fields data — 7
dataobjectThe department as it now stands. Same shape as the detail endpoint.
Errors 3
not_found404No such department.
name_required422A name is empty in one of the languages you sent.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/admins/departments/4' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"names":{"tr":"Genel Destek"},"appointees":[1,5,8]}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/departments/${did}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
names: { en: 'General Support' },
appointees: [1, 5, 8],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/departments/' . $did);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'names' => ['en' => 'General Support'],
'appointees' => [1, 5, 8],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The staff list REPLACES what was there: read the current one before adding to it.
$d = Api::Admins()->GetDepartment(['did' => $did])['data'];
$d['appointee_ids'][] = $newStaffId;
Api::Admins()->UpdateDepartment([
'did' => $did, 'appointees' => $d['appointee_ids'],
]);
```
#### Removing a Department
delete/api/v1/admin/admins/departments/{did}
`Admins/DeleteDepartment` admin
Removes a department.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the department removed.
Errors 3
not_found404No such department.
blocked_by_gate422A hook refused the delete.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/admins/departments/4' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/departments/${did}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/departments/' . $did);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Move the tickets sitting there to another department BEFORE removing this one.
Api::Tickets()->UpdateTicket(['id' => $ticketId, 'department_id' => $otherDid]);
Api::Admins()->DeleteDepartment(['did' => $did]);
```
#### Removing the Icon
delete/api/v1/admin/admins/departments/{did}/icon
`Admins/DeleteDepartmentIcon` admin
Removes a department's image icon.
Response fields data — 7
dataobjectThe department as it now stands. The icon type falls back to the typeface.
Errors 2
not_found404No such department.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/admins/departments/4/icon' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/admins/departments/${did}/icon`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/admins/departments/' . $did . '/icon');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The removal drops the file and turns the type back to a typeface; the icon can stay empty.
Api::Admins()->DeleteDepartmentIcon(['did' => $did]);
Api::Admins()->UpdateDepartment(['did' => $did, 'icon' => 'fa-solid fa-globe']);
```
### Pitfalls
> **A department with no staff orphans its tickets**
>
> When no staff are assigned to a department, a ticket landing there **can be assigned to nobody** and the picker on the ticket comes back empty. The department still shows and clients still choose it, so the gap surfaces only once a ticket arrives. Sweep the listing for empty staff lists.
> **The staff list replaces what was there**
>
> The staff list you send on an update **replaces** what was assigned. Sending only the person you meant to add takes the others out of the department and changes what tickets they see. Read the detail first and merge the list.
> **Creating wants every language, updating does not**
>
> Creating a department wants a name in **every live language** on the installation, and the call is refused when one is missing. An update touches only the languages you send and keeps the rest. Reading the two behaviours as one surfaces as an unexpected error at creation.
> **Move the tickets before removing**
>
> Removing a department **takes the footing away** from the tickets bound to it. The tickets do not vanish, yet they point at a department that no longer exists and grow harder to find in the listings. Move them to another department first.
> **Removing the icon puts nothing in its place**
>
> The endpoint that removes an image icon drops the file and turns the type back to a typeface, while **putting nothing in its place**. With the typeface field empty the department shows with no icon at all. Writing a typeface icon after the removal is usually the step you want.
### Related Articles
- [Staff Accounts](https://dev.wisecp.com/en/staff-accounts)
- [Ticket Reference Lists](https://dev.wisecp.com/en/ticket-reference-lists)
- [Staff Privilege Groups](https://dev.wisecp.com/en/staff-privilege-groups)
# API / Admin API / Affiliates
## Affiliate Partners
https://dev.wisecp.com/en/affiliate-partners
The four endpoints that see, search, switch and remove the partners in the program.
### Overview
The affiliate program is where a client earns commission on the customers their own link brings in. This article manages the **people** in that program: who is there, who is on and who goes.
Every record carries **two numbers**. `id` belongs to the partner record and `owner_id` to the client behind it. The assignment endpoints speak the client number, so mixing the two makes a quiet wrong assignment.
The search endpoint sits here because it feeds the assignment screens: an interface that does not know the number types a name first, then hands the number it gets to the assignment.
### Reference
#### Listing the Partners
get/api/v1/admin/affiliates
`Affiliates/GetAffiliates` admin
Returns the partners in the program with their earnings and referral totals.
Query 4
pageintWhich page.
limitintRecords per page. 100 at the most.
searchstringSearches the name, company, e-mail, partner id and client id.
statusstringThe status filter: `active` or `inactive`.
Response fields data[] — 13 + meta — 4
idintThe partner record id.
owner_idintThe client behind the partner. This is the number assignments use.
user_idintThe same client id. A second name coming from the query join.
full_namestringThe client's name.
company_namestringThe company name.
emailstringThe e-mail address.
disabledintWhether it is off. 0 means on and 1 means off.
balancestringThe earnings waiting to be paid. Text with four decimals.
currencyintThe currency id of the earnings.
referralsintHow many clients they referred.
hitsintHow many clicks their link took.
total_paidstringWhat has been paid out so far. It counts completed requests alone.
datestringWhen they joined the program.
totalintHow many partners there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/affiliates?status=active&limit=50' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates?status=active', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const owing = data.filter((a) => Number(a.balance) > 0);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates?status=active');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// id belongs to the PARTNER and owner_id to the CLIENT behind it; assignments speak owner_id.
$rows = Api::Affiliates()->GetAffiliates([], ['status' => 'active'])['data'];
$byClient = array_column($rows, 'balance', 'owner_id');
```
#### Searching Partners, Clients and Services
get/api/v1/admin/affiliates/select
`Affiliates/SelectForAffiliate` admin 10 results at most
The search behind the assignment screens; you type a name instead of an id.
Query 2
typestringWhat to look for: `affiliate`, `client` or `service`. It looks for a partner by default.
qstringThe search text. It is taken under the name `search` as well.
Response fields data — 2
typestringThe kind searched. The same one you sent.
resultsobject[] results[]What was found.
idintThe id of the record found.
textstringThe label to show. A service gets its id and name, a person their name and company.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/affiliates/select?type=client&q=jane' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/affiliates/select');
url.searchParams.set('type', 'client');
url.searchParams.set('q', term);
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$qs = http_build_query(['type' => 'client', 'q' => $term]);
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/select?' . $qs);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// It returns 10 results at most: this is a search box and not a listing.
$hits = Api::Affiliates()->SelectForAffiliate([], ['type' => 'client', 'q' => $term])['data'];
$exact = count($hits['results']) === 1 ? $hits['results'][0]['id'] : 0;
```
#### Turning a Partner On and Off
put/api/v1/admin/affiliates/{aid}/status
`Affiliates/SetAffiliateStatus` admin
Turns a partner on or takes them out of the program.
Body 1
enabledboolreqWhether the partner is on. It becomes the opposite-named field on the record.
Response fields data — 2
idintThe partner id.
enabledboolWhere it now stands.
Errors 2
not_found404No such partner.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/affiliates/7/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":false}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/affiliates/${aid}/status`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: false }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/' . $aid . '/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => false]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Turning a partner off DOES NOT wipe the earnings: the balance stays and payouts can still be asked for.
Api::Affiliates()->SetAffiliateStatus(['aid' => $aid, 'enabled' => false]);
```
#### Removing a Partner
delete/api/v1/admin/affiliates/{aid}
`Affiliates/DeleteAffiliate` admin cannot be undone
Removes a partner along with every record tied to them.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the partner removed.
Errors 2
not_found404No such partner.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/affiliates/7' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/affiliates/${aid}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/' . $aid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The panel asks for an admin password here while the API needs the scope alone. Consider turning them off first.
Api::Affiliates()->SetAffiliateStatus(['aid' => $aid, 'enabled' => false]);
// Api::Affiliates()->DeleteAffiliate(['aid' => $aid]); // the earnings history goes as well
```
### Pitfalls
> **Two numbers: the partner id and the client id**
>
> In the listing `id` is the partner record and `owner_id` the client behind it. The link kept on the client record also holds the **client number** rather than the partner one. Keep the two apart, since the assignment and status endpoints want different numbers.
> **Being off is spoken with two opposite words**
>
> The listing gives a `disabled` field where **0 means on**. The status endpoint takes `enabled` where **true means on**. They are opposite names for one thing, and copying one into the other flips the state.
> **Removing takes the earnings history too**
>
> Removing a partner also takes the commission entries, the payout requests, the clicks, the history and the referral records, while the linked clients lose their link. The panel asks for an admin password at this step and the API settles for the scope. Turn a partner off rather than remove them when you mean to part ways.
> **The search endpoint gives ten results at most**
>
> The search endpoint is a search box and not a listing: it returns ten results at most no matter how many match, and there is no paging. Resting bulk work on it drops everything past the tenth without a word. Use the listing endpoint for the full set.
> **The paid total counts completed requests alone**
>
> The `total_paid` field is the sum of completed payout requests. A waiting or in-flight request does not enter that number, and it is not taken out of `balance` either. Do not answer "what do we owe" by adding the two figures.
### Related Articles
- [Affiliate Assignments](https://dev.wisecp.com/en/affiliate-assignments)
- [Affiliate Payout Requests](https://dev.wisecp.com/en/affiliate-payout-requests)
- [Affiliate Program Settings](https://dev.wisecp.com/en/affiliate-program-settings)
## Affiliate Program Settings
https://dev.wisecp.com/en/affiliate-program-settings
The two endpoints holding the commission rate, period, delay and payout floor.
### Overview
The program settings decide **how much** commission is given, **when** and **for how long**. Two endpoints read and write one structure.
Three settings work together: the rate sets the size of the commission, the period says whether it comes once or on every renewal, and the delay says when the earnings count as payable.
The cookie duration answers a separate question: how many days after a click on the link a visitor can become a customer and still be credited to that partner.
### Reference
#### Reading the Program Settings
get/api/v1/admin/affiliates/config
`Affiliates/GetAffiliateConfig` admin
Returns every setting of the affiliate program.
Response fields data — 11
enabledboolWhether the program is on. Service assignment is refused while it is off.
view_without_membershipboolWhether the program page opens to someone with no account.
show_commission_ratesboolWhether commission rates show on the product page.
commission_periodstringWhether commission comes once or on every renewal: `onetime` or `lifetime`.
commission_delayintThe days waited before commission counts as usable.
ratefloatThe default commission rate. A product can carry its own.
min_paymentobject min_paymentThe least that can be asked for in a payout.
amountfloatThe least amount.
currency_idintThe currency id of that amount.
cookie_durationintHow many days a referral is remembered.
redirectstringWhere a click on the link lands. The home page when empty.
payment_gatewaysobject[]The payout methods a partner can pick. Each element is an object holding a name per language.
contentobjectThe program page text per language.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/affiliates/config' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/config', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const rate = data.rate;
const floor = data.min_payment.amount;
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/config');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Read here BEFORE saving: the save writes a default over any field you leave out.
$cfg = Api::Affiliates()->GetAffiliateConfig()['data'];
$cfg['rate'] = 15;
```
#### Saving the Program Settings
put/api/v1/admin/affiliates/config
`Affiliates/SaveAffiliateConfig` admin a full write
Writes the whole set of settings and returns where they now stand.
Body 11
enabledboolWhether the program is on. Service assignment is refused while it is off.
view_without_membershipboolWhether the program page opens to someone with no account.
show_commission_ratesboolWhether commission rates show on the product page.
commission_periodstringWhether commission comes once or on every renewal: `onetime` or `lifetime`.
commission_delayintThe days waited before commission counts as usable.
ratefloatThe default commission rate. A product can carry its own.
min_paymentobject min_paymentThe least that can be asked for in a payout.
amountfloatThe least amount.
currency_idintThe currency id of that amount.
cookie_durationintHow many days a referral is remembered.
redirectstringWhere a click on the link lands. The home page when empty.
payment_gatewaysobject[]The payout methods a partner can pick. Each element is an object holding a name per language.
contentobjectThe program page text per language.
Response fields data — 11
dataobjectThe settings as they now stand. Same shape as the read endpoint.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/affiliates/config' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true,"commission_period":"lifetime","commission_delay":30,"rate":10,"cookie_duration":30,"min_payment":{"amount":50,"currency_id":840}}'
```
```javascript
const read = await fetch('https://panel.example.com/api/v1/admin/affiliates/config', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data: cfg } = await read.json();
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/config', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ...cfg, rate: 15 }),
});
```
```php
$cfg = $current; // GET /affiliates/config yaniti
$cfg['rate'] = 15;
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/config');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($cfg),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A FULL WRITE: every field you leave out returns to its default (texts and payout methods GO EMPTY).
$cfg = Api::Affiliates()->GetAffiliateConfig()['data'];
$cfg['rate'] = 15;
Api::Affiliates()->SaveAffiliateConfig($cfg);
```
### Pitfalls
> **The save is a full write and not a patch**
>
> The save endpoint writes **every field** in the body. A field you leave out is not kept and returns to its default: numbers to zero, texts to empty, the payout methods and program texts to an empty list. To change the rate alone, read first and write over the object that comes back.
> **The payout methods are a list and not a language map**
>
> The program text is an object with a key per language. The payout methods are a **list** whose every element holds a name per language of its own. Writing them the same way empties the method list, and partners see no option when asking for a payout.
> **The commission period is not checked**
>
> The period field is cleaned up alone and **not checked** against the values that are known. A misspelled value saves without a word, no error comes back, and the period does not behave as you expect. Read the value back after saving.
> **Turning the program off does not wipe existing earnings**
>
> While the program is off a new service assignment is refused, and existing balances and waiting payout requests stay where they are. Turning it off stops new commission from being made rather than freezing what exists.
### Related Articles
- [Affiliate Partners](https://dev.wisecp.com/en/affiliate-partners)
- [Affiliate Assignments](https://dev.wisecp.com/en/affiliate-assignments)
- [Affiliate Payout Requests](https://dev.wisecp.com/en/affiliate-payout-requests)
## Affiliate Payout Requests
https://dev.wisecp.com/en/affiliate-payout-requests
The three endpoints that see and settle the payout requests partners open.
### Overview
A partner cannot take the commission they earn straight away; they open a **payout request** and the team approves it. This article covers the three endpoints that see and settle those requests.
A request sits in one of five states: waiting, in process, completed, refused or cancelled. Only **completed** is the moment the money truly leaves, and it comes off the partner's balance.
What happens to the balance matters here: an approval takes the money down, a removal gives it back, and a refusal **leaves the balance alone**. Reading the three as one shows the partner a wrong figure.
### Reference
#### Listing the Payout Requests
get/api/v1/admin/affiliates/withdrawals
`Affiliates/GetWithdrawals` admin
Returns the payout requests the partners opened.
Query 4
pageintWhich page.
limitintRecords per page. 100 at the most.
searchstringSearches the name, company, e-mail, payout method and request id.
statusstringThe status filter: `awaiting`, `process`, `completed`, `rejected` or `cancelled`.
Response fields data[] — 15 + meta — 4
idintThe request id.
affiliate_idintThe partner record that opened it.
owner_idintThe client behind the partner.
user_idintThe same client id. A second name coming from the query join.
full_namestringThe client's name.
company_namestringThe company name.
emailstringThe e-mail address.
amountstringThe amount asked for. Text with four decimals.
currencyintThe currency id of the amount.
gatewaystringThe payout method the partner picked.
gateway_infostringThe detail for that method. An account number or e-mail.
statusstringWhere the request stands.
status_msgstringThe note written on the status.
ctimestringWhen the request was opened.
updated_atstringWhen it last changed.
totalintHow many requests there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/affiliates/withdrawals?status=awaiting' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/withdrawals?status=awaiting', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data, meta } = await res.json();
const owed = data.reduce((s, w) => s + Number(w.amount), 0);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/withdrawals?status=awaiting');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The amounts sit in EACH REQUEST's own currency; convert before adding them up.
$rows = Api::Affiliates()->GetWithdrawals([], ['status' => 'awaiting'])['data'];
$byCurrency = [];
foreach ($rows as $w) $byCurrency[$w['currency']] = ($byCurrency[$w['currency']] ?? 0) + (float) $w['amount'];
```
#### Handling Requests in Bulk
post/api/v1/admin/affiliates/withdrawals/bulk
`Affiliates/BulkWithdrawals` admin touches the balance
Approves, refuses or removes several payout requests.
Body 2
actionstringreqWhat to do: `approve`, `reject` or `delete`.
idsint[]reqThe request ids to work on. An id that is not found gets skipped without a word.
Response fields data — 2
actionstringThe job applied.
processedint[]The ids you sent. Not the ones that truly changed.
Errors 3
action_invalid422The job name is none of the three values.
ids_required422No request id was given.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/affiliates/withdrawals/bulk' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"approve","ids":[3,5]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/withdrawals/bulk', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ action: 'approve', ids: [3, 5] }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/withdrawals/bulk');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['action' => 'approve', 'ids' => [3, 5]]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// APPROVE takes it off the balance and REJECT DOES NOT give it back; delete is the one job that refunds.
Api::Affiliates()->BulkWithdrawals(['action' => 'approve', 'ids' => [3, 5]]);
// approved by mistake: delete rather than reject
Api::Affiliates()->BulkWithdrawals(['action' => 'delete', 'ids' => [3]]);
```
#### Removing One Request
delete/api/v1/admin/affiliates/withdrawals/{wid}
`Affiliates/DeleteWithdrawal` admin
Removes one payout request and gives the amount back where needed.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the request removed.
Errors 2
not_found404No such request.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/affiliates/withdrawals/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/affiliates/withdrawals/${wid}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/withdrawals/' . $wid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The one difference from a bulk delete: a missing id gives 404 here and is skipped in bulk.
Api::Affiliates()->DeleteWithdrawal(['wid' => $wid]);
```
### Pitfalls
> **A refusal does not give the balance back**
>
> An approval takes the amount off the partner's balance. A refusal **writes the status alone** and does not put the amount back, so refusing a request you approved leaves the money short on that balance for good. The way back from a wrong approval is **removal** and not refusal.
> **Approve, refuse, approve again takes it twice**
>
> An approval takes from the balance only while the request is **not already completed**. Refusing an approved request and approving it again drops the state out of completed, so it takes a second time and the partner loses twice for one payout. Check the balance by hand after a round like that.
> **The list that comes back does not say what was handled**
>
> The `processed` field is the same set of **ids you sent**. A request that is not found gets skipped without a word, while its id still shows in that list. Read the statuses back from the listing endpoint to see that bulk work landed.
> **The balance never goes below zero**
>
> Every job that takes from the balance stops at zero. Approving a request larger than the balance leaves it at zero and the **difference disappears** with no error. Compare the request amount against the partner's balance before approving.
> **Two ways to remove, one difference**
>
> Removing one request and removing many do the same job, and both give the amount back on a completed request. The one difference is a missing id: the single endpoint answers `404` while the bulk one skips quietly. The single endpoint is safer for an id you are unsure of.
### Related Articles
- [Affiliate Partners](https://dev.wisecp.com/en/affiliate-partners)
- [Affiliate Assignments](https://dev.wisecp.com/en/affiliate-assignments)
- [Affiliate Program Settings](https://dev.wisecp.com/en/affiliate-program-settings)
## Affiliate Assignments
https://dev.wisecp.com/en/affiliate-assignments
The six endpoints that link, list and unlink clients and services against a partner.
### Overview
A partner earns in two ways. A **client link** says "they brought this customer in", while a **service link** writes commission on one particular sale.
The two live in different places. A client link is a field on the client record, and a service link opens a commission record of its own. That is why the two removal endpoints speak different numbers.
Linking a service looks for five conditions. The program has to be on and the service type suitable. The product must stay open to commission, the partner switched on, and the service free of another partner.
### Reference
#### Listing the Linked Clients
get/api/v1/admin/affiliates/assigned-clients
`Affiliates/GetAssignedClients` admin
Returns the clients linked to a partner.
Query 3
pageintWhich page.
limitintRecords per page. 100 at the most.
searchstringSearches the client and partner name along with the company.
Response fields data[] — 8 + meta — 4
idintThe client id.
full_namestringThe client's name.
company_namestringThe client's company.
emailstringThe client's e-mail.
aff_idintThe **client** number of the partner they are linked to. Not the partner record id.
aff_namestringThe partner's name.
aff_companystringThe partner's company.
aff_user_idintThe partner's client id.
totalintHow many linked clients there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/affiliates/assigned-clients?search=jane' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/assigned-clients', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const perPartner = Object.groupBy(data, (c) => c.aff_user_id);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/assigned-clients');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// aff_id is the partner's CLIENT number; do not try to match it with the partner record id.
$rows = Api::Affiliates()->GetAssignedClients()['data'];
$mine = array_filter($rows, fn ($c) => (int) $c['aff_user_id'] === $partnerClientId);
```
#### Linking a Client to a Partner
post/api/v1/admin/affiliates/assigned-clients
`Affiliates/AssignClient` admin
Marks a client as a partner's referral.
Body 2
affiliate_idintreqThe partner record id.
client_idintreqThe id of the client to link.
Response fields data — 3
assignedboolWhether the link was made.
affiliate_idintThe partner id.
client_idintThe client id.
Errors 4
missing_params422The partner or client id is missing.
assign_self422A client cannot be linked to their own partnership.
not_found404No such partner or client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/affiliates/assigned-clients' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"affiliate_id":7,"client_id":88}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/assigned-clients', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ affiliate_id: 7, client_id: 88 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/assigned-clients');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['affiliate_id' => 7, 'client_id' => 88]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A client tied to another partner is taken over SILENTLY; the first partner loses the referral.
$rows = Api::Affiliates()->GetAssignedClients()['data'];
$owned = array_column($rows, 'aff_user_id', 'id');
if (! isset($owned[$clientId])) Api::Affiliates()->AssignClient(['affiliate_id' => $aid, 'client_id' => $clientId]);
```
#### Removing a Client Link
delete/api/v1/admin/affiliates/assigned-clients
`Affiliates/UnassignClients` admin
Takes the partner link off one client or more.
Body 1
idsint[]reqThe **client** ids. Not assignment ids.
Response fields data — 1
unassignedint[]The client ids you sent.
Errors 2
ids_required422No client id was given.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/affiliates/assigned-clients' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ids":[88,90]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/assigned-clients', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ids: [88, 90] }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/assigned-clients');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['ids' => [88, 90]]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// There is NO check: the link goes off every client you send, and unlinked ones fill the answer too.
Api::Affiliates()->UnassignClients(['ids' => [88, 90]]);
```
#### Listing the Linked Services
get/api/v1/admin/affiliates/assigned-services
`Affiliates/GetAssignedServices` admin
Returns the service records earning partners their commission.
Query 4
pageintWhich page.
limitintRecords per page. 100 at the most.
searchstringSearches the client, partner, service name and record id.
statusstringThe record status filter.
Response fields data[] — 15 + meta — 4
idintThe commission record id. The removal endpoint wants this number.
affiliate_idintThe partner record id.
service_idintThe service id.
service_namestringThe service name.
user_idintThe id of the client owning the service.
full_namestringThe client's name.
company_namestringThe client's company.
amountstringThe service amount. What the commission is worked out from.
currencyintThe currency id of the amount.
commissionstringThe commission written to the partner.
statusstringWhere the record stands. A completed one already went to the balance.
aff_namestringThe partner's name.
aff_companystringThe partner's company.
aff_user_idintThe partner's client id.
ctimestringWhen the record was opened.
totalintHow many records there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/affiliates/assigned-services?limit=50' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/assigned-services', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const earned = data.reduce((s, t) => s + Number(t.commission), 0);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/assigned-services');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The removal endpoint wants the RECORD id from here rather than the SERVICE id.
$rows = Api::Affiliates()->GetAssignedServices()['data'];
$recordId = array_column($rows, 'id', 'service_id')[$serviceId] ?? 0;
```
#### Linking a Service to a Partner
post/api/v1/admin/affiliates/assigned-services
`Affiliates/AssignService` admin five conditions
Links a service to a partner and opens the commission record.
Body 2
affiliate_idintreqThe partner record id.
service_idintreqThe id of the service to link.
Response fields data — 3
assignedboolWhether the link was made.
affiliate_idintThe partner id.
service_idintThe service id.
Errors 8
missing_params422The partner or service id is missing.
system_disabled422The affiliate program is off.
type_unsupported422The service type does not take commission. Hosting, server, software and special types pass.
product_disabled422The affiliate program is off for this product.
affiliate_disabled422The partner is off.
already_assigned422The service is linked to another partner.
not_found404No such partner or service.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/affiliates/assigned-services' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"affiliate_id":7,"service_id":305}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/affiliates/assigned-services', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ affiliate_id: 7, service_id: 305 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/assigned-services');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['affiliate_id' => 7, 'service_id' => 305]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Five conditions are checked at once; the two missed most are an off program and a service already linked.
try { Api::Affiliates()->AssignService(['affiliate_id' => $aid, 'service_id' => $sid]); }
catch (\Throwable $e) { $skipped[$sid] = $e->getMessage(); }
```
#### Removing a Service Link
delete/api/v1/admin/affiliates/assigned-services/{tid}
`Affiliates/UnassignService` admin touches the balance
Removes the commission record and takes the commission back where needed.
Response fields data — 2
unassignedboolWhether the removal ran.
idintThe id of the record removed.
Errors 2
not_found404No such commission record.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/affiliates/assigned-services/12' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/affiliates/assigned-services/${tid}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/affiliates/assigned-services/' . $tid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// On a completed record the commission comes OFF the balance; the OPPOSITE way to a payout removal.
Api::Affiliates()->UnassignService(['tid' => $recordId]);
```
### Pitfalls
> **The two removal endpoints want two different numbers**
>
> The endpoint removing a client link wants **client ids** in the body. The one removing a service link wants the **commission record id** in the address. Handing the second a service id either answers not found or removes the wrong record. Take the record id from the listing endpoint.
> **Removing a client link checks nothing**
>
> This endpoint takes the link off every client id you send. It never looks at whether the id was linked to a partner, nor whether that client exists. All of them count as **removed** in the answer. A wrong list quietly cuts other clients' links.
> **A link silently takes over an existing one**
>
> When a client is already linked to another partner the new link raises no error. It **writes over** the old one, and the first partner loses that referral. On the service side the same case is refused with `already_assigned`. Check the existing link from the listing endpoint before linking a client.
> **Removing a commission record takes from the balance**
>
> Removing a completed commission record **takes** the amount off the partner's balance. Remember that removing a payout request **adds** to it: the two removals work in opposite directions. The balance never goes below zero, so a difference that cannot be taken disappears without a word.
> **The link field holds a client id and not a partner id**
>
> The `aff_id` in the listing is the **client behind the partner** and not the partner record id. The linking endpoint, meanwhile, wants the partner record id in the body. Passing a number read from one listing straight into the other assigns to a different partner.
> **The service type and product setting form a quiet gate**
>
> Commission is written on hosting, server, software and special services alone, and other types such as a domain get `type_unsupported`. The product's own setting can close commission as well. Gather those two cases apart during bulk linking work.
### Related Articles
- [Affiliate Partners](https://dev.wisecp.com/en/affiliate-partners)
- [Affiliate Payout Requests](https://dev.wisecp.com/en/affiliate-payout-requests)
- [Affiliate Program Settings](https://dev.wisecp.com/en/affiliate-program-settings)
# API / Admin API / Automation
## Automation Jobs
https://dev.wisecp.com/en/automation-jobs
The ten endpoints that watch the jobs in three queues and handle them one by one or in bulk.
### Overview
The automation carries **three queues**: the scheduled tasks, the module calls and the notices. In each, job rows wait, run, complete or fail, and these ten endpoints work with those rows.
The dashboard gives everything in **one call**: the worker's health, the queue counts, the task list, the recent jobs and the last twenty-four hours as a chart. Reach for it when writing monitoring rather than making five calls.
Four endpoints touch one job (retry, cancel, clear the lock, delete), and **three reach the whole queue**. Those last three move hundreds of jobs with one call and cannot be undone.
### Reference
#### Reading the Dashboard
get/api/v1/admin/automation/dashboard
`Automation/GetAutomationDashboard` admin
Returns the whole state of the automation in one call.
Query 3
chart_rangestringThe span the chart covers.
chart_stagestringLimits the chart to one stage.
chart_taskstringNarrows the chart to a single task.
Response fields data — 5
statusobjectThe worker as it stands: its health, its last run, how long ago that was, how long to the next, which task is next and how many jobs wait.
statsobjectThe queue and system counts: per queue the waiting, running, completed today and failed; across the system the open jobs, the waiting jobs, the longest wait and the gap between runs.
tasksarrayThe task list: its name, its shown name, its frequency, whether it is off, how many jobs wait and run, how many completed and failed today, and its last error.
jobsobjectThe last fifty job rows, the total job count and the state of the restore suspicion.
chartarrayThe last twenty-four hours broken down by type into successes and failures.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/dashboard' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/dashboard', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
if (data.status.status !== 'ok') console.warn('worker', data.status.status);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/dashboard');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// ONE call is enough for monitoring; the dashboard carries what five endpoints would.
$d = Api::Automation()->GetAutomationDashboard()['data'];
$healthy = $d['status']['status'] === 'ok';
```
#### Listing the Jobs
get/api/v1/admin/automation/jobs
`Automation/GetAutomationJobs` admin cursor paging
Returns the queue feed, newest first.
Query 2
limitintHow many rows to return. Clamped between ten and two hundred.
before_idintFetches rows older than this id. This is how you page backwards.
Response fields data — 4
jobsarrayThe job rows: id, type, title, status, label, time, attempt count and estimated start.
totalintHow many rows the queue holds. It comes back on the first feed alone.
restore_activeboolWhether a restore is suspected. It comes back on the first feed alone.
has_moreboolWhether older rows remain. It comes back on a cursor call alone.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/jobs?limit=50' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/automation/jobs');
url.searchParams.set('limit', '50');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
// Daha eskisi: url.searchParams.set('before_id', data.jobs.at(-1).id)
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs?' . http_build_query(['limit' => 50]));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The total and the restore mark come on the FIRST call alone; a cursor call carries neither.
$first = Api::Automation()->GetAutomationJobs()['data'];
$older = Api::Automation()->GetAutomationJobs([], [
'before_id' => end($first['jobs'])['id'],
]);
```
#### Reading One Job
get/api/v1/admin/automation/jobs/{queue}/{id}
`Automation/GetAutomationJob` admin
Returns a job's whole row with its payload and logs.
Path 2
queuestringWhich queue: `cron`, `module`, `notification`.
idintThe job id.
Response fields data
idintThe job id.
typestringThe job type.
statusstringThe job status.
attemptsintHow many times it was tried.
created_atstringWhen it joined the queue.
completed_atstringWhen it finished.
payloadobjectThe data given to the job. It arrives decoded.
process_logsobjectThe logs kept while it ran.
result_payloadobjectWhat the job left behind.
result_summaryobjectA readable summary of the result. It comes back on the scheduled-task queue.
Errors 4
invalid_queue422The queue key is not recognised.
invalid_id422The job id is not valid.
not_found404No such job.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/jobs/cron/9001' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/automation/jobs/cron/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The fields differ BY QUEUE; read past the common ones without assuming they are there.
$job = Api::Automation()->GetAutomationJob(['queue' => 'cron', 'id' => $id])['data'];
$logs = $job['process_logs'] ?? [];
```
#### Retrying a Job
post/api/v1/admin/automation/jobs/{queue}/{id}/retry
`Automation/RetryAutomationJob` admin
Puts a job back among the waiting.
Body —
——No body is needed. The queue and the id in the path name the job; send an empty body.
Response fields data — 3
retriedboolWhether the call ran.
queuestringThe job's queue.
idintThe job id.
Errors 3
invalid_queue422The queue key is not recognised.
invalid_id422The job id is not valid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/jobs/cron/9001/retry' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/automation/jobs/cron/${id}/retry`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/' . $id . '/retry');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The attempt counter is CLEARED: a job that fails again looks as though it started afresh.
Api::Automation()->RetryAutomationJob(['queue' => 'cron', 'id' => $id]);
```
#### Cancelling a Job
post/api/v1/admin/automation/jobs/{queue}/{id}/cancel
`Automation/CancelAutomationJob` admin
Marks a job cancelled.
Body —
——No body is needed. The queue and the id in the path name the job; send an empty body.
Response fields data — 3
cancelledboolWhether the call ran.
queuestringThe job's queue.
idintThe job id.
Errors 3
invalid_queue422The queue key is not recognised.
invalid_id422The job id is not valid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/jobs/cron/9001/cancel' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/automation/jobs/cron/${id}/cancel`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/' . $id . '/cancel');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Cancelling does not stop a job ALREADY RUNNING; it changes the queue row's status.
Api::Automation()->CancelAutomationJob(['queue' => 'cron', 'id' => $id]);
```
#### Clearing a Stuck Lock
post/api/v1/admin/automation/jobs/{queue}/{id}/reclaim
`Automation/ReclaimAutomationJob` admin risks a double run
Clears the lock a crashed worker left on a job.
Body —
——No body is needed. The queue and the id in the path name the job; send an empty body.
Response fields data — 3
reclaimedboolWhether the call ran.
queuestringThe job's queue.
idintThe job id.
Errors 3
invalid_queue422The queue key is not recognised.
invalid_id422The job id is not valid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/jobs/cron/9001/reclaim' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/automation/jobs/cron/${id}/reclaim`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/' . $id . '/reclaim');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// If the worker IS STILL ALIVE the job runs twice; check the longest wait first.
$d = Api::Automation()->GetAutomationDashboard()['data'];
if ($d['status']['status'] === 'dead')
Api::Automation()->ReclaimAutomationJob(['queue' => 'cron', 'id' => $id]);
```
#### Deleting a Job
delete/api/v1/admin/automation/jobs/{queue}/{id}
`Automation/DeleteAutomationJob` admin
Removes a job row from the queue.
Response fields data — 3
deletedboolWhether the delete ran.
queuestringThe job's queue.
idintThe id of the job removed.
Errors 3
invalid_queue422The queue key is not recognised.
invalid_id422The job id is not valid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/automation/jobs/cron/9001' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/automation/jobs/cron/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Cancel rather than delete: the record stays and the job is never picked up again.
Api::Automation()->CancelAutomationJob(['queue' => 'cron', 'id' => $id]);
```
#### Deleting Many Jobs
post/api/v1/admin/automation/jobs/{queue}/bulk-delete
`Automation/BulkDeleteAutomationJobs` admin
Removes the job ids you give in one call.
Body 1
idsint[]reqThe job ids to remove. Zero and below are dropped, and repeats are folded.
Response fields data — 3
deletedboolWhether the call ran.
queuestringThe queue the jobs were in.
countintHow many were removed.
Errors 3
invalid_queue422The queue key is not recognised.
ids_required422No job id was given.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/jobs/cron/bulk-delete' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ids":[9001,9002,9003]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/jobs/cron/bulk-delete', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ids: [9001, 9002, 9003] }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/bulk-delete');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['ids' => [9001, 9002, 9003]]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The count can come back BELOW what you sent: ids from another queue are not removed.
$n = Api::Automation()->BulkDeleteAutomationJobs([
'queue' => 'cron', 'ids' => $ids,
])['data']['count'];
```
#### Retrying Everything That Failed
post/api/v1/admin/automation/jobs/{queue}/retry-all-failed
`Automation/RetryAllFailedAutomationJobs` admin the whole queue
Puts every failed job in a queue back among the waiting.
Body —
——No body is needed. The queue comes from the path and the set cannot be narrowed: every failed job in it is taken. Send an empty body.
Response fields data — 2
retriedboolWhether the call ran.
queuestringThe queue worked on. How many jobs it touched is not returned.
Errors 2
invalid_queue422The queue key is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/jobs/cron/retry-all-failed' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/jobs/cron/retry-all-failed', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/retry-all-failed');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Hundreds that failed FOR ONE REASON all run again at once and fail again.
// Read the reason from one job's detail first, then make this call.
Api::Automation()->RetryAllFailedAutomationJobs(['queue' => 'cron']);
```
#### Cancelling Everything Waiting
post/api/v1/admin/automation/jobs/{queue}/cancel-all-pending
`Automation/CancelAllPendingAutomationJobs` admin the whole queue
Cancels every job waiting in a queue.
Body —
——No body is needed. The queue comes from the path and the set cannot be narrowed: every pending job in it is cancelled. Send an empty body.
Response fields data — 2
cancelledboolWhether the call ran.
queuestringThe queue worked on. How many were cancelled is not returned.
Errors 2
invalid_queue422The queue key is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/jobs/cron/cancel-all-pending' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/jobs/cron/cancel-all-pending', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/jobs/cron/cancel-all-pending');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The waiting jobs are INVOICES, NOTICES and provider calls; they all drop at once.
Api::Automation()->CancelAllPendingAutomationJobs(['queue' => 'cron']);
```
### Pitfalls
> **The queue-wide endpoints cannot be undone**
>
> Retrying everything failed and cancelling everything waiting move **hundreds of jobs in one call**, and neither says which. Cancelling the waiting drops invoices not yet issued, notices not yet sent and provider calls not yet made, all at once. Look at the feed first to see what is there.
> **Clearing a lock can run a job twice**
>
> The reclaim endpoint **assumes the worker died**. If it is still alive the job gets picked up a second time and the same invoice can be issued twice. Read the worker health on the dashboard before using it; on a live worker a job that looks stuck is usually only slow.
> **Cancelling does not stop a running job**
>
> The cancel endpoint **changes the queue row's status** and does not kill a running process. Cancelling a job in flight does not cut it short; when it ends it writes its own result. When something truly has to stop, switching the cron off is the only way.
> **A retry clears the attempt counter**
>
> Retrying a job **clears its attempt counter**. A job that failed three times looks as though it is running for the first time, and failing again starts the count at one. A check that sifts troubled jobs by their attempt count will miss the difference.
> **A bulk delete is bound to its queue**
>
> A bulk delete looks **only in the queue named in the path**, and ids from another are passed over quietly. A count below what you sent is no error; those ids live elsewhere. When removing a mixed list, group the ids by queue and make separate calls.
### Related Articles
- [Scheduled Tasks](https://dev.wisecp.com/en/scheduled-tasks)
- [Cron Settings](https://dev.wisecp.com/en/cron-settings)
- [Queue Maintenance](https://dev.wisecp.com/en/queue-maintenance)
## Scheduled Tasks
https://dev.wisecp.com/en/scheduled-tasks
The four endpoints that list scheduled tasks, switch them and run them by hand.
### Overview
A scheduled task is the **definition** of work an installation does by itself: issuing invoices, suspending services, sending notices. These four endpoints list the tasks, show their jobs, switch them on and off and run them by hand.
A task and a job are **not the same**. A task is a rule, and every run of it leaves one or more jobs in the queue. The counts in the task list describe that rule's jobs.
Some tasks run in **two stages**: one that works out what to do, and one that carries out what was found. The counts and the filters respect that split.
### Reference
#### Listing the Tasks
get/api/v1/admin/automation/tasks
`Automation/GetAutomationTasks` admin
Returns every scheduled task on the installation with its state.
Response fields data[] — 14
taskstringThe task key. The other endpoints take this value.
display_namestringThe name it shows under.
descriptionstringWhat the task does.
frequencystringHow often it runs: `minute`, `hour`, `day`, `month`, `unknown`.
disabledboolWhether the task was switched off.
registeredboolWhether a handler exists to carry the task out. When false the task sits in the list unable to run.
last_run_atstring | nullWhen it last ran.
next_run_atstring | nullWhen it next runs.
pendingintHow many jobs wait.
processingintHow many are running.
today_completedintHow many completed today. On a two-stage task only the execute stage counts.
today_failedintHow many failed. Counted across the period the records are kept.
last_errorstring | nullThe last error message.
last_error_atstring | nullWhen that error happened.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/tasks' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/tasks', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const broken = data.filter((t) => ! t.registered);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// SWITCHED OFF and NO HANDLER are different things: the second points at a gap in setup.
$tasks = Api::Automation()->GetAutomationTasks()['data'];
$broken = array_filter($tasks, fn ($t) => ! $t['registered']);
```
#### Listing a Task's Jobs
get/api/v1/admin/automation/tasks/{task}/jobs
`Automation/GetAutomationTaskJobs` admin cursor paging
Returns the queue jobs belonging to one task.
Query 5
status_filterstringFilters by status.
stage_filterstringFilters by stage. On a two-stage task the discovery and the execution are separate.
qstringSearches the rows freely.
after_idintFetches rows after this id.
limitintHow many rows to return. Clamped between one and a hundred.
Response fields data — 3
rowsarrayThe job rows.
has_moreboolWhether more rows remain.
next_afterintThe id to hand to the next page.
Errors 2
task_required422No task key was given.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/tasks/invoice-create/jobs?limit=50' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL(`https://panel.example.com/api/v1/admin/automation/tasks/${task}/jobs`);
url.searchParams.set('limit', '50');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
// Sonraki sayfa: url.searchParams.set('after_id', data.next_after)
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks/' . $task . '/jobs?' . http_build_query(['limit' => 50]));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This endpoint walks FORWARD while the general feed walks back. Do not mix the two.
$page = Api::Automation()->GetAutomationTaskJobs(['task' => $task], ['limit' => 50])['data'];
$next = Api::Automation()->GetAutomationTaskJobs(['task' => $task], [
'after_id' => $page['next_after'],
]);
```
#### Switching a Task On and Off
put/api/v1/admin/automation/tasks/{task}/status
`Automation/UpdateAutomationTaskStatus` admin
Decides whether a task runs at all.
Body 1
enabledintreqSwitches the task on or off.
Response fields data — 2
taskstringThe task key.
enabledboolHow the task now stands.
Errors 4
enabled_required422Neither on nor off was given.
task_required422No task key was given.
not_found404No such task.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/automation/tasks/invoice-create/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":0}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/automation/tasks/${task}/status`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: 0 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks/' . $task . '/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => 0]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Switching off does not clear the QUEUE: what waits is picked up once it comes back on.
Api::Automation()->UpdateAutomationTaskStatus(['task' => $task, 'enabled' => 0]);
```
#### Running a Task Now
post/api/v1/admin/automation/tasks/{task}/run
`Automation/RunAutomationTask` admin it gets queued
Queues a task without waiting for its time.
Body —
——No body is needed, send an empty one. The task key in the path says which one to run.
Response fields data — 3
taskstringThe task key.
dispatchedboolWhether it went into the queue. It does not mean the task finished.
job_idintThe id of the job opened.
Errors 4
task_required422No task key was given.
no_handler422The task has no handler.
blocked_by_gate422A hook refused the run.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/tasks/invoice-create/run' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/automation/tasks/${task}/run`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.job_id);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/tasks/' . $task . '/run');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The call QUEUES the task rather than running it; follow the result by the job id.
$jobId = Api::Automation()->RunAutomationTask(['task' => $task])['data']['job_id'];
$job = Api::Automation()->GetAutomationJob(['queue' => 'cron', 'id' => $jobId])['data'];
```
### Pitfalls
> **Switched off and missing a handler are different**
>
> A task can be **switched off**, or it can have **no handler at all**. The second is not a choice but a gap in the setup: the task sits in the list, never runs, and the run-now call errors. Read the two fields apart when writing monitoring.
> **Running now does not run now**
>
> The run endpoint **puts the task in the queue**, and the scheduled worker does the work. By the time the response arrives the job may not have started, so follow the job id that comes back to see the outcome. With a dead worker the job is never picked up and waits quietly.
> **The two listings walk opposite ways**
>
> The task-jobs endpoint pages **forward**: it fetches what comes after the id you give. The general job feed goes **backward**. Code using both in one loop and mixing up the cursor fields either never advances or returns the same page.
> **Switching off does not empty the queue**
>
> Switching a task off stops it **leaving new jobs** and does not clear what already waits. Switch it back on and those older jobs get picked up too, running at a moment you did not expect. For a task going off for a long while, consider cancelling what waits as well.
> **Today's counts look at different windows**
>
> In the task list the completed count covers **today** while the failed count covers the **whole period** the records are kept. Putting the two side by side to work out a success rate gives a wrong answer. For counts over one window, count the task's jobs yourself with the status filter.
### Related Articles
- [Automation Jobs](https://dev.wisecp.com/en/automation-jobs)
- [Cron Settings](https://dev.wisecp.com/en/cron-settings)
- [Adding a Scheduled Job](https://dev.wisecp.com/en/adding-a-scheduled-task)
## Cron Settings
https://dev.wisecp.com/en/cron-settings
The four endpoints for the automation's configuration, its main switch and its cron secret.
### Overview
These four endpoints configure the **automation itself**: how long records are kept, which hours heavy work runs in, whether the automation is on at all, and the secret guarding the cron address.
The main switch is an **emergency stop**. With it off no task runs: no invoice is issued, no service renewed, no notice sent. Who switched it off and when stays recorded in the settings.
The secret is the cron address's **password** and cannot be read; the settings say only whether one is set. Renewing hands it back once and makes the old address invalid.
### Reference
#### Reading the Settings
get/api/v1/admin/automation/settings
`Automation/GetAutomationSettings` admin
Returns the automation's configuration and the state of its main switch.
Response fields data — 8
cron_enabledboolWhether the automation's main switch is on.
disabled_atstring | nullWhen it was switched off.
disabled_bystring | nullWho switched it off.
time_windowobjectThe window heavy work runs in: its start and its end.
retentionobjectHow long records are kept: separate day counts for completed, cancelled and failed jobs.
secret_setboolWhether the cron secret is set. The secret itself never comes back.
restoreobjectThe restore suspicion: when it arose and how many hours of silence it rests on.
tasksobjectThe task definitions as they stand.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/settings' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/settings', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The secret NEVER comes back: only a mark saying whether one is set.
$s = Api::Automation()->GetAutomationSettings()['data'];
$ready = $s['cron_enabled'] && $s['secret_set'];
```
#### Writing the Settings
put/api/v1/admin/automation/settings
`Automation/UpdateAutomationSettings` admin
Writes how long records are kept and the window work runs in.
Body 4
completed_daysintHow many days completed jobs are kept. One day at the least.
cancelled_daysintHow many days cancelled jobs are kept.
failed_daysintHow many days failed jobs are kept.
time_windowobjectThe window heavy work runs in: a start and an end time. It has to span at least an hour past the start of the day.
Response fields data — 8
dataobjectThe settings as they now stand. Same shape as the read endpoint.
Errors 3
invalid_window422The window is too short.
config_write_failed422The settings file could not be written.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/automation/settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"completed_days":30,"failed_days":30,"time_window":{"start":"00:00","end":"06:00"}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/settings', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
completed_days: 30,
cancelled_days: 7,
failed_days: 30,
time_window: { start: '00:00', end: '06:00' },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'completed_days' => 30,
'failed_days' => 30,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// SHORTENING the retention does not clear the past at once; the clean-up is its own call.
Api::Automation()->UpdateAutomationSettings(['completed_days' => 7]);
```
#### Stopping the Automation
put/api/v1/admin/automation/cron-enabled
`Automation/ToggleAutomationCron` admin stops everything
Switches the automation's main switch on or off.
Body 1
enabledintreqSwitches the automation on, or stops it outright.
Response fields data — 2
cron_enabledboolHow the switch now stands.
changedboolWhether anything moved. False means it already stood that way.
Errors 3
enabled_required422Neither on nor off was given.
blocked_by_gate422A hook refused the switch-off.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/automation/cron-enabled' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":0}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/cron-enabled', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: 0 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/cron-enabled');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => 0]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Switching off stops INVOICING, RENEWALS and notices alike; keep it for maintenance.
Api::Automation()->ToggleAutomationCron(['enabled' => 0]);
// ... maintenance ...
Api::Automation()->ToggleAutomationCron(['enabled' => 1]);
```
#### Renewing the Secret
post/api/v1/admin/automation/cron-secret/regenerate
`Automation/RegenerateAutomationCronSecret` admin breaks the old address
Builds a new secret for the cron address and returns it.
Body —
——No body is needed; send an empty one. This endpoint takes no parameters, so the new secret cannot be chosen.
Response fields data — 1
secretstringThe new secret. It cannot be read again, so write it into the scheduled call on the server at once.
Errors 2
config_write_failed422The settings file could not be written.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/cron-secret/regenerate' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/cron-secret/regenerate', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
// data.secret yalnizca burada gorunur
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/cron-secret/regenerate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Renewing makes the OLD cron address invalid: nothing runs until the scheduled call on
// the server is updated.
$secret = Api::Automation()->RegenerateAutomationCronSecret()['data']['secret'];
```
### Pitfalls
> **The main switch stops everything**
>
> Switching the automation off stops not one task but **all of them**: no invoice, no renewal, no suspension, no notice. While it stays off the jobs pile up in the queue, and they all begin running at once when it comes back. When switching off for maintenance, keep the window short.
> **The new secret shows once**
>
> The renew call returns the secret **in that response alone**, and the settings endpoint never gives it again. Miss it and you cannot update the scheduled call on the server, leaving another renewal as the only way out. A client that logs its responses logs the secret too.
> **Renewing breaks the old address**
>
> The secret is part of the cron address. The moment it changes, the scheduled call on the server **keeps using the old one** and gets refused, so the automation stops until the address is updated. The outage is quiet: nothing shows as an error, the jobs merely begin piling up.
> **The window holds heavy work back**
>
> The window keeps heavy tasks to **certain hours alone**. A narrow one can leave the night's work unfinished by morning and the queue a little longer each day. When narrowing it, watch the longest wait on the dashboard; a growing figure says the window is too small.
> **Shortening the retention does not clear the past**
>
> Lowering the retention days changes only **what the next clean-up measures by**; the older rows stay until it runs. To free space, run the clean-up rather than changing the setting and waiting, and look at the preview first to see what would go.
### Related Articles
- [Queue Maintenance](https://dev.wisecp.com/en/queue-maintenance)
- [Automation Jobs](https://dev.wisecp.com/en/automation-jobs)
- [Scheduled Tasks](https://dev.wisecp.com/en/scheduled-tasks)
## Queue Maintenance
https://dev.wisecp.com/en/queue-maintenance
The five endpoints that clear the queues, measure them and handle the restore warning.
### Overview
Queues grow over time. These five endpoints deal with **maintenance**: clearing old jobs, seeing how much room the tables take, and handling the warning that appears when the database is restored.
The clean-up comes in two steps. The preview **counts and removes nothing**, while the run takes away for good the jobs that outlived the retention. The measure is the retention days in the automation settings.
The restore warning arises when the automation notices it has been **silent for a long while**. That usually means the database came back from an older backup, and the queue may hold work that will run again or that is long past.
### Reference
#### Previewing the Clean-Up
get/api/v1/admin/automation/cleanup/preview
`Automation/PreviewAutomationCleanup` admin it removes nothing
Shows how many jobs the retention rules would remove.
Response fields data — 4
completedintHow many completed jobs would go.
cancelledintHow many cancelled jobs would go.
failedintHow many failed jobs would go.
retentionobjectThe retention days the counts rest on.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/cleanup/preview' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/cleanup/preview', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const willGo = data.completed + data.cancelled + data.failed;
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/cleanup/preview');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This endpoint COUNTS rather than removes; always look here before a clean-up.
$plan = Api::Automation()->PreviewAutomationCleanup()['data'];
if ($plan['completed'] + $plan['cancelled'] + $plan['failed'] > 0)
Api::Automation()->RunAutomationCleanup();
```
#### Running the Clean-Up
post/api/v1/admin/automation/cleanup/run
`Automation/RunAutomationCleanup` admin a permanent delete
Removes for good the jobs that outlived the retention.
Body —
——No body is needed, send an empty one. The retention comes from the automation settings, not from the call, so there is no field to widen or narrow the sweep with.
Response fields data — 2
deletedintHow many jobs were removed.
breakdownobjectThe breakdown by status: completed, cancelled and failed.
Errors 2
blocked_by_gate422A hook refused the clean-up.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/cleanup/run' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/cleanup/run', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.deleted, data.breakdown);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/cleanup/run');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// What goes never returns: the error messages on failed jobs go along with them.
$r = Api::Automation()->RunAutomationCleanup()['data'];
```
#### Reading the Table Sizes
get/api/v1/admin/automation/table-stats
`Automation/GetAutomationTableStats` admin
Returns the row count and the average data size of the three queue tables.
Response fields data — 3
cronjob_queueobjectThe scheduled-task queue: its row count and average data size.
module_queueobjectThe module queue: its row count and average data size.
notification_queueobjectThe notice queue: its row count and average data size.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/automation/table-stats' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/table-stats', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/table-stats');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Growth is the row count TIMES the average size rather than the count; read both.
$t = Api::Automation()->GetAutomationTableStats()['data'];
$approx = $t['cronjob_queue']['rows'] * $t['cronjob_queue']['avg_payload'];
```
#### Dismissing the Restore Warning
post/api/v1/admin/automation/restore/dismiss
`Automation/DismissAutomationRestore` admin
Takes away the restore-suspicion warning.
Body —
——No body is needed, send an empty one. The endpoint takes nothing: it clears the suspicion marks kept in the settings.
Response fields data — 1
dismissedboolWhether the warning was taken away.
Errors 2
config_write_failed422The settings file could not be written.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/restore/dismiss' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/restore/dismiss', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/restore/dismiss');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Dismissing does not remove the REASON; find out where the silence came from first.
$s = Api::Automation()->GetAutomationSettings()['data'];
if ($s['restore']['suspected_at'] !== null)
Api::Automation()->DismissAutomationRestore();
```
#### Starting a Restore Reconciliation
post/api/v1/admin/automation/restore/trigger
`Automation/TriggerAutomationRestore` admin the panel asks for a password
Marks the queue for reconciliation after a restore.
Body —
——No body is needed, send an empty one. The endpoint takes nothing: the suspicion time it writes is the moment of the call.
Response fields data — 1
triggeredboolWhether the mark was set.
Errors 2
config_write_failed422The settings file could not be written.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/automation/restore/trigger' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/automation/restore/trigger', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/automation/restore/trigger');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// In the panel this asks for the ADMIN PASSWORD; over the API the key's scope is the only gate.
Api::Automation()->TriggerAutomationRestore();
```
### Pitfalls
> **Count first, remove after**
>
> The clean-up run **cannot be undone** and does not say in advance how many records will go. The preview exists for exactly that: it counts by the same measure and touches nothing. After changing the retention days, running the clean-up without looking can take far more than you expected.
> **A removed job takes its error with it**
>
> The clean-up removes failed jobs too, and their **error messages go with them**. Running it while looking into a problem can take away the very evidence you need. Keeping the retention on failed jobs longer than on completed ones is worth doing for that reason.
> **The row count alone does not tell the size**
>
> The table figures give both the row count and the **average data size**. A queue with few rows carrying large data can take more room than a busy one carrying little. When watching growth, multiply the two; counting rows alone misleads.
> **Dismissing the warning leaves the cause**
>
> Dismissing the restore warning only **clears the mark** and changes nothing about why the queue fell silent. When the warning really follows a restore, work long past sits in the queue and runs all at once when things resume. Look at the dates on the recent jobs before dismissing it.
> **The panel's password gate is not here**
>
> Starting a restore reconciliation asks for the **administrator password** in the panel, while here the key's scope is the only gate. A key carrying that scope can do outright what the panel guards with a second check. Weigh that when handing keys out.
### Related Articles
- [Cron Settings](https://dev.wisecp.com/en/cron-settings)
- [Automation Jobs](https://dev.wisecp.com/en/automation-jobs)
- [Scheduled Tasks](https://dev.wisecp.com/en/scheduled-tasks)
# API / Admin API / Clients
## Client Addresses
https://dev.wisecp.com/en/client-addresses
The five endpoints that read, add, update and delete an address in a client's address book.
### Overview
A client can hold several addresses, and an invoice is issued to one of them. The address book is separate from the client record.
One address is the default. Making a new address the default clears the flag on the previous one; there is never more than one default.
> **Notification preferences**
>
> A notification preference is stored as a bitmask: one number carrying several choices.
### Reference
#### Listing Addresses
get/api/v1/admin/clients/{id}/addresses
`Clients/GetClientAddresses` admin
Returns the client's whole address book. The default one is flagged with `is_default`.
Response fields data[] — 17
idintAddress id.
full_namestringFull name.
labelstringAddress label, for example `Office`.
typestring`individual` or `corporate`.
emailstringEmail address.
phonestringPhone; digits only are stored.
identitystringIdentity or tax number.
companyobject 3 fieldsTax details on a corporate address.
namestringTrading name.
tax_numberstringTax number.
tax_officestringTax office.
country_idintCountry id. Resolve with `reference/countries`.
statestringState or region.
citystringCity.
addressstringStreet address.
zipcodestringPostcode. At most 20 characters.
is_defaultboolWhether this is the default address.
email_notificationsintEmail notification preference (bitmask).
sms_notificationsintSMS notification preference (bitmask).
statusstring`active` or `passive`.
Errors 2
not_found404No such client or address.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/addresses' \
-H "Authorization: Bearer $API_KEY" \
-H 'Accept: application/json'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientAddresses(['id' => 42]);
foreach ($response['data'] as $address) {
if ($address['is_default']) {
$invoiceAddress = $address;
}
}
```
#### Adding an Address
post/api/v1/admin/clients/{id}/addresses
`Clients/CreateClientAddress` admin
Adds a record to the address book and returns it in the same schema as the list.
Body 16 fields, 5 required
full_namestringrequiredFull name.
emailstringrequiredValidated for format.
country_idintrequiredCountry id. List: `reference/countries`.
statestringrequiredState or region.
citystringrequiredCity.
typestring`individual` or `corporate`. Defaults to `individual`.
labelstringAddress label.
phonestringPhone; digits only are stored.
identitystringIdentity or tax number.
companyobject 3 fieldsTax details on a corporate address.
namestringTrading name.
tax_numberstringTax number.
tax_officestringTax office.
addressstringStreet address.
zipcodestringPostcode. At most 20 characters.
is_defaultboolMakes this the default address.
email_notificationsintEmail notification preference. Defaults to all on.
sms_notificationsintSMS notification preference. Defaults to all on.
overwrite_invoicesboolApplies this address to the client's open invoices as well.
Response fields data
dataobjectThe address created, returned with `201`. Same shape as the list schema.
Errors 4
not_found404No such client or address.
email_invalid422Email format is not valid.
address_add_failed500The record could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/addresses' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'full_name' => 'John Doe',
'email' => 'john@example.com',
'country_id' => 840,
'state' => 'California',
'city' => 'San Francisco',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClientAddress([
'id' => 42,
'full_name' => 'John Doe',
'email' => 'john@example.com',
'country_id' => 840,
'state' => 'California',
'city' => 'San Francisco',
'is_default' => true,
]);
$addressId = $response['data']['id'] ?? 0;
```
Response 201 422
```json
{
"data": {
"id": 13,
"full_name": "John Doe",
"type": "individual",
"country_id": 840,
"city": "San Francisco",
"zipcode": "94105",
"is_default": true,
"status": "active"
}
}
```
```json
{
"error": {
"code": "email_invalid",
"message": "A valid email is required."
}
}
```
#### Address Detail
get/api/v1/admin/clients/{id}/addresses/{addr_id}
`Clients/GetClientAddress` admin
Returns one address. The schema is the same as in the list.
Response fields data
dataobjectThe address itself. Same shape as the list schema.
Errors 2
not_found404No such client or address.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientAddress(['id' => 42, 'addr_id' => 13]);
```
#### Updating an Address
put/api/v1/admin/clients/{id}/addresses/{addr_id}
`Clients/UpdateClientAddress` admin full replace
Updates the address. The body takes **the same fields as create**, and the required ones stay required.
Body the same 16 fields as create
full_namestringrequiredFull name.
emailstringrequiredValidated for format.
country_idintrequiredCountry id.
statestringrequiredState or region.
citystringrequiredCity.
overwrite_invoicesboolApplies the change to the client's open invoices as well.
Response fields data
dataobjectThe address after the update. Same shape as the list schema.
Errors 7
not_found404No such client or address.
full_name_required422`full_name` is required.
email_invalid422A valid email is required.
country_required422`country_id` is required.
state_required422`state` is required.
city_required422`city` is required.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({"full_name":"John Doe","email":"john@example.com","country_id":840,"state":"California","city":"San Francisco","address":"123 Market Street","zipcode":"94105","is_default":true}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($address),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The required fields are sent again: this is a full update, not a partial one.
$response = Api::Clients()->UpdateClientAddress([
'id' => 42,
'addr_id' => 13,
'full_name' => 'John Doe',
'email' => 'john@example.com',
'country_id' => 840,
'state' => 'California',
'city' => 'San Francisco',
]);
```
#### Deleting an Address
delete/api/v1/admin/clients/{id}/addresses/{addr_id}
`Clients/DeleteClientAddress` admin
Deletes the address and returns the id that was removed.
Response fields data
deletedboolWhether the delete succeeded.
idintId of the deleted address.
Errors 1
not_found404No such client or address.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/addresses/13' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/addresses/13', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/addresses/13');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientAddress(['id' => 42, 'addr_id' => 13]);
```
### Pitfalls
> **There is only one default**
>
> Flagging an address with `is_default` clears the flag on the previous one. You do not have to update the old address; two defaults cannot exist.
> **Open invoices do not change by themselves**
>
> Updating an address does not reach invoices that were already issued. Send `overwrite_invoices` if you want it to.
> **The update is not partial**
>
> The endpoint is `PUT`. Leave a required field out and the request is refused; sending only the changed field is not enough.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
## Client Notes
https://dev.wisecp.com/en/client-internal-notes
The four endpoints that read, add, update and delete the internal notes attached to a client.
### Overview
A note is an **internal** line attached to the client record. The client never sees it on any screen; only operators working in the panel read it.
A note can be pinned. Pinned notes sit at the top of the list and the rest run newest to oldest.
### Reference
#### Listing Notes
get/api/v1/admin/clients/{id}/notes
`Clients/GetClientNotes` admin
Returns the client's notes. The order is fixed: pinned first, then newest to oldest.
Response fields data[] — 6
idstringNote id. A string, not a number.
contentstringThe note text.
pinnedboolWhether the note is pinned.
added_byintId of the admin who added it.
added_by_namestringDisplay name of whoever added it.
created_atstringCreation time.
Errors 2
not_found404No such client or note.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/notes' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/notes', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/notes');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientNotes(['id' => 42]);
foreach ($response['data'] as $note) {
if ($note['pinned']) {
$highlight[] = $note['content'];
}
}
```
#### Adding a Note
post/api/v1/admin/clients/{id}/notes
`Clients/CreateClientNote` admin
Adds a note to the client. The owner of the calling key is recorded as the author.
Body 2
contentstringrequiredThe note text.
pinnedboolPins the note to the top of the list. Defaults to `false`.
Response fields data
dataobjectThe note created, returned with `201`. Same shape as the list schema.
Errors 4
not_found404No such client.
content_required422The content is empty.
note_add_failed500The note could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/notes' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"content":"Clean payment history, priority client","pinned":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/notes', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({"content":"Clean payment history, priority client","pinned":true}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/notes');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'content' => 'Clean payment history, priority client',
'pinned' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClientNote([
'id' => 42,
'content' => 'Clean payment history, priority client',
'pinned' => true,
]);
```
#### Updating a Note
patch/api/v1/admin/clients/{id}/notes/{note_id}
`Clients/UpdateClientNote` admin pinning lives here too
Changes the note text or its pinned state. You have to send at least one field.
Body at least one
contentstringThe new text. If sent, it cannot be empty.
pinnedboolPins or unpins the note.
Response fields data
dataobjectThe note after the update. Same shape as the list schema.
Errors 4
not_found404No such client or note.
content_required422The content was sent empty.
note_update_failed500The note could not be updated.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/notes/a1b2c3' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"pinned":false}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/notes/a1b2c3', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ pinned: false }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/notes/a1b2c3');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['pinned' => false]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Unpinning goes through this endpoint too; there is no separate action.
$response = Api::Clients()->UpdateClientNote([
'id' => 42,
'note_id' => 'a1b2c3',
'pinned' => false,
]);
```
#### Deleting a Note
delete/api/v1/admin/clients/{id}/notes/{note_id}
`Clients/DeleteClientNote` admin
Deletes the note.
Response fields data
deletedboolWhether the delete succeeded.
idstringId of the deleted note.
Errors 3
not_found404No such client or note.
note_delete_failed500The note could not be deleted.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/notes/a1b2c3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/notes/a1b2c3', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/notes/a1b2c3');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientNote([
'id' => 42,
'note_id' => 'a1b2c3',
]);
```
### Pitfalls
> **A note id is not a number**
>
> Unlike the other resources, `id` here is a string (`a1b2c3`). Code that casts it to a number will not find the record.
> **There is no separate pin endpoint**
>
> In the panel pinning looks like its own action; in the API `pinned` is a field like any other and goes through the update endpoint.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
## Client Credit
https://dev.wisecp.com/en/client-credit
The five endpoints that read a client's prepaid balance, adjust it and wire it to automatic payment.
### Overview
Credit is the prepaid balance sitting on a client's account. These endpoints manage the **manual** adjustments to it; money taken by a payment provider does not come through here.
Every record carries a direction: `up` raises the balance, `down` lowers it. The amount is always positive.
### Reference
#### Listing Credit Records
get/api/v1/admin/clients/{id}/credits
`Clients/GetClientCredits` admin
Returns the ledger of manual adjustments made to the client's balance.
Response fields data[] — 7
idintId of the credit record.
typestring`up` raises the balance, `down` lowers it.
amountnumberAmount. Rounded to two decimals and always positive; the direction is carried by `type`.
currency_idintCurrency id of the record.
descriptionstringDescription.
added_byintId of the admin who added it.
created_atstringCreation time.
Errors 2
not_found404No such client or credit record.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/credits' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/credits', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/credits');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientCredits(['id' => 42]);
$added = 0.0;
foreach ($response['data'] as $entry) {
if ($entry['type'] === 'up') {
$added += (float) $entry['amount'];
}
}
```
#### Adding Credit
post/api/v1/admin/clients/{id}/credits
`Clients/CreateClientCredit` admin moves the balance
Writes a manual adjustment to the balance and returns the balance after it.
Body 3
typestringrequired`up` or `down`.
amountnumberrequiredMust be greater than zero. Read in the client's balance currency.
descriptionstringDescription. It shows in the ledger.
Response fields data — 2
creditobjectThe record that was created, in the same schema as the list.
new_balancenumberThe balance after the adjustment.
Errors 4
not_found404No such client or credit record.
type_invalid422`type` is neither `up` nor `down`.
amount_invalid422The amount is zero or negative.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/credits' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"up","amount":50,"description":"Manual top-up"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/credits', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({"type":"up","amount":50,"description":"Manual top-up"}),
});
const body = await res.json();
console.log(body.data.new_balance);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/credits');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'type' => 'up',
'amount' => 50,
'description' => 'Manual top-up',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClientCredit([
'id' => 42,
'type' => 'up',
'amount' => 50,
'description' => 'Manual top-up',
]);
$balance = $response['data']['new_balance'] ?? null;
```
Response 201 422
```json
{
"data": {
"credit": {
"id": 10,
"type": "up",
"amount": 50.00,
"currency_id": 1,
"description": "Manual top-up",
"added_by": 1,
"created_at": "2026-06-21 12:00:00"
},
"new_balance": 150.00
}
}
```
```json
{
"error": {
"code": "amount_invalid",
"message": "Amount must be greater than zero."
}
}
```
#### Updating a Credit Record
patch/api/v1/admin/clients/{id}/credits/{log_id}
`Clients/UpdateClientCredit` admin
Corrects an existing record. If the amount or the direction changes, the balance is recalculated.
Body at least one
typestring`up` or `down`.
amountnumberAn amount greater than zero.
descriptionstringDescription.
Response fields data — 2
creditobjectThe updated record, in the same schema as the list.
new_balancenumberThe recalculated balance.
Errors 4
not_found404No such client or credit record.
type_invalid422`type` is neither `up` nor `down`.
amount_invalid422The amount is zero or negative.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/credits/10' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"amount":75}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/credits/10', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ amount: 75 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/credits/10');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['amount' => 75]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UpdateClientCredit([
'id' => 42,
'log_id' => 10,
'amount' => 75,
]);
```
#### Deleting a Credit Record
delete/api/v1/admin/clients/{id}/credits/{log_id}
`Clients/DeleteClientCredit` admin reverses the balance
Deletes the record and reverses its effect on the balance.
Response fields data — 3
deletedboolWhether the delete succeeded.
idintThe deleted credit record's ID.
new_balancenumberThe balance after the reversal.
Errors 2
not_found404No such client or credit record.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/credits/10' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/credits/10', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/credits/10');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientCredit([
'id' => 42,
'log_id' => 10,
]);
```
#### Paying Automatically from Credit
put/api/v1/admin/clients/{id}/credit-autopay
`Clients/SetClientCreditAutopay` admin
Sets whether invoices are paid from the balance without asking.
Body 1
enabledboolrequiredWhen on, a due invoice is taken from the balance.
Response fields data
enabledboolThe auto-pay state after the call.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/credit-autopay' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/credit-autopay', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: true }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/credit-autopay');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SetClientCreditAutopay([
'id' => 42,
'enabled' => true,
]);
```
### Pitfalls
> **Deleting reverses the balance**
>
> Deleting a record does not only remove the line; the amount comes back out of the balance. Closing a wrong adjustment with a second record in the opposite direction leaves a clearer trail.
> **The amount is read in the client's currency**
>
> The number you send is in the client's balance currency; the request carries no currency. An integration working across currencies has to convert on its own side.
> **Autopay does not reach the past**
>
> Turning it on does not pay the invoices already waiting; it applies to the ones that fall due afterwards.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
## Blacklist and Duplicates
https://dev.wisecp.com/en/blacklist-and-duplicates
The four endpoints that blacklist a client, take them off the list, and find accounts that might be the same person.
### Overview
These endpoints do two jobs together: blacklisting a client, and finding other accounts that **might be the same person**. They belong to one decision — someone who gets blacklisted usually comes back with a second account.
Blacklisting is more than a flag: you choose which restrictions come with it. Switch none on and the client is only marked.
### Reference
#### Blacklist Status
get/api/v1/admin/clients/{id}/blacklist
`Clients/GetClientBlacklist` admin
Returns whether the client is blacklisted, why, and which restrictions are on.
Response fields data — 6
blacklistedboolWhether the client is blacklisted.
reasonstringThe reason. Values: `payment_fraud` · `chargeback` · `abuse` · `spam` · `tos_violation` · `false_info` · `other`
notesstringA free-text note.
restrictionsobject 4 fieldsThe restrictions that are on.
block_new_ordersboolBlocks new orders.
block_renewalsboolBlocks renewals.
block_ticketsboolBlocks opening tickets.
suspend_servicesboolSuspends the services.
blacklisted_bystringName of the admin who blacklisted.
blacklisted_atstringWhen the client was blacklisted.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/blacklist' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/blacklist', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/blacklist');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientBlacklist(['id' => 42]);
if ($response['data']['blacklisted'] ?? false) {
$reason = $response['data']['reason'];
}
```
#### Blacklisting a Client
post/api/v1/admin/clients/{id}/blacklist
`Clients/CreateClientBlacklist` admin can suspend services
Blacklists the client and applies the restrictions you choose.
Body 3
reasonstringrequiredThe reason. Values: `payment_fraud` · `chargeback` · `abuse` · `spam` · `tos_violation` · `false_info` · `other`
notesstringA free-text note explaining the decision.
restrictionsobject 4 fieldsWhich restrictions to switch on. Send none and none are applied; the client is only flagged.
block_new_ordersboolBlocks new orders.
block_renewalsboolBlocks renewals.
block_ticketsboolBlocks opening tickets.
suspend_servicesboolSuspends the services.
Response fields data
dataobjectThe blacklist record, returned with `201`. Same shape as the status endpoint above.
Errors 4
not_found404No such client.
reason_invalid422The reason is not one of the allowed values.
blocked_by_gate422A hook on `gate:user.blacklist_add` vetoed the operation.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/blacklist' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"reason":"chargeback","notes":"Two chargebacks","restrictions":{"block_new_orders":true,"suspend_services":true}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/blacklist', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({"reason":"chargeback","notes":"Two chargebacks","restrictions":{"block_new_orders":true,"suspend_services":true}}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/blacklist');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'reason' => 'chargeback',
'notes' => 'Two chargebacks',
'restrictions' => [
'block_new_orders' => true,
'suspend_services' => true,
],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClientBlacklist([
'id' => 42,
'reason' => 'chargeback',
'notes' => 'Two chargebacks',
'restrictions' => [
'block_new_orders' => true,
'suspend_services' => true,
],
]);
```
#### Removing from the Blacklist
delete/api/v1/admin/clients/{id}/blacklist
`Clients/DeleteClientBlacklist` admin
Removes the blacklist record. Bringing suspended services back is a separate choice.
Body 1
reactivate_servicesboolReactivates the services that this blacklisting suspended. Leave it out and they stay suspended.
Response fields data
removedboolWhether the removal succeeded.
Errors 3
not_found404No such client.
not_blacklisted422The client is not on the blacklist.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/blacklist' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"reactivate_services":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/blacklist', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ reactivate_services: true }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/blacklist');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['reactivate_services' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientBlacklist([
'id' => 42,
'reactivate_services' => true,
]);
```
#### Duplicate Account Scan
get/api/v1/admin/clients/{id}/duplicates
`Clients/GetClientDuplicates` admin IP · name · company
Returns other accounts that share the client's IP, name or company name.
Response fields data — 2
currentobjectA summary of the client under review: `id`, `full_name`, `company_name`, `ip`, `created_at`.
matchesobject[] 7 fieldsThe matching accounts.
idintId of the matching client.
full_namestringFull name.
company_namestringCompany name.
ipstringThe IP recorded at sign-up.
created_atstring | nullSign-up date.
days_apartintDays between the two sign-up dates. An absolute value.
match_typesstring[]What matched: `ip`, `name`, `company`.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/duplicates' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/duplicates', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
const sameIp = body.data.matches.filter((m) => m.match_types.includes('ip'));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/duplicates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientDuplicates(['id' => 42]);
foreach ($response['data']['matches'] as $match) {
// Same IP a few days apart is a stronger signal than a name match.
if (in_array('ip', $match['match_types'], true) && $match['days_apart'] < 7) {
$suspects[] = $match['id'];
}
}
```
Response 200
```json
{
"data": {
"current": {
"id": 42,
"full_name": "John Doe",
"company_name": "",
"ip": "203.0.113.10",
"created_at": "2026-01-01 10:00:00"
},
"matches": [
{
"id": 57,
"full_name": "J. Doe",
"company_name": "",
"ip": "203.0.113.10",
"created_at": "2026-01-03 09:20:00",
"days_apart": 2,
"match_types": ["ip", "name"]
}
]
}
}
```
### Pitfalls
> **Removing does not bring services back**
>
> Removing the blacklist record does not reactivate suspended services on its own. Send `reactivate_services` if you want them back; otherwise the client is off the list while the services stay suspended.
> **A match is not a verdict**
>
> The same IP can be a home or an office, and the same name can be a coincidence. Read `match_types` together with `days_apart`: two accounts opened from one IP days apart is a far stronger signal than two that only share a name.
> **The scan reads the sign-up IP**
>
> The address compared is the IP from **sign-up**, not the last sign-in. On a long-lived account that address can be years old.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
## Client Security
https://dev.wisecp.com/en/client-security-endpoints
The five endpoints that manage the password, verification, two-step sign-in and the security rules set on a client.
### Overview
These five endpoints carry the security decisions an **operator** applies to a client account: setting the password, marking a field verified, turning on two-step verification, tightening sign-in and payment rules, and limiting support access.
None of them ask the client anything. They all apply directly, which is why a key carrying these endpoints is worth keeping narrow.
### Reference
#### Changing the Password
put/api/v1/admin/clients/{id}/password
`Clients/SetClientPassword` admin no old password asked
Sets the client's password directly. The current one is not asked for.
Body 2
passwordstringrequiredThe new password. At least `options/password-length` characters; defaults to 6.
password_confirmationstringIf sent, it must match `password` exactly. Leave it out and no check is made.
Response fields data — 1
changedboolWhether the password was changed.
Errors 5
not_found404No such client.
password_required422The password is empty.
password_too_short422The password is below the minimum length. The limit comes back in `error.details.min`.
password_mismatch422The confirmation does not match the password.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/password' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"password":"Str0ngP@ssw0rd","password_confirmation":"Str0ngP@ssw0rd"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/password', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
password: 'Str0ngP@ssw0rd',
password_confirmation: 'Str0ngP@ssw0rd',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/password');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'password' => $newPassword,
'password_confirmation' => $newPassword,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SetClientPassword([
'id' => 42,
'password' => $newPassword,
]);
```
#### Verifying Email and Phone
post/api/v1/admin/clients/{id}/verify
`Clients/VerifyClient` admin
Marks a field as verified. No code is sent to the client; the flag is set directly.
Body 1
typestringrequired`email` or `phone`.
Response fields data — 2
verifiedboolWhether the verification was applied.
typestringThe field that was verified: `email` or `phone`.
Errors 3
not_found404No such client.
type_invalid422`type` is neither of the two values.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/verify' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"email"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/verify', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ type: 'email' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/verify');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['type' => 'email']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// You set the flag here after running your own verification flow.
$response = Api::Clients()->VerifyClient([
'id' => 42,
'type' => 'email',
]);
```
#### Two-Step Verification
put/api/v1/admin/clients/{id}/2fa
`Clients/SetClient2fa` admin
Turns the client's two-step verification on or off.
Body 2
enabledboolrequiredTurns it on or off.
methodstringName of the Authentication module to use, for example `GoogleAuthenticator`. Required only when enabling; not needed to disable.
Response fields data — 2
enabledboolThe two-step state as it now stands.
methodstringThe module that was selected. Comes back only when enabling.
Errors 3
not_found404No such client.
method_required422`method` was missing on an enable request.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/2fa' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true,"method":"GoogleAuthenticator"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/2fa', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: true, method: 'GoogleAuthenticator' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/2fa');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'enabled' => true,
'method' => 'GoogleAuthenticator',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// You do not need to send a method when turning it off.
$response = Api::Clients()->SetClient2fa([
'id' => 42,
'enabled' => false,
]);
```
#### Security Settings
patch/api/v1/admin/clients/{id}/security-settings
`Clients/UpdateClientSecuritySettings` admin
Changes the security rules that apply to this client. Only the fields you send change.
Body 6
block_proxyboolBlocks sign-in from behind a proxy.
allow_proxyboolExempts this client from the proxy check.
require_birthdayboolMakes the date of birth required.
require_adult_ageboolRequires an over-18 check.
force_document_filtersint[]Ids of the document verification filters to enforce. List: `clients/document-filters`.
blocked_gatewaysstring[]Keys of the payment methods closed to this client.
Response fields data — 6
block_proxyboolWhether sign-in from behind a proxy is blocked. The whole state comes back, not only the part you sent.
allow_proxyboolWhether the client is exempt from the proxy check.
require_birthdayboolWhether the date of birth is required.
require_adult_ageboolWhether the over-18 check is on.
force_document_filtersint[]Ids of the enforced document verification filters.
blocked_gatewaysstring[]Keys of the payment methods closed to this client.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/security-settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"block_proxy":true,"blocked_gateways":["PayPal"]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/security-settings', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ block_proxy: true, blocked_gateways: ['PayPal'] }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/security-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'block_proxy' => true,
'blocked_gateways' => ['PayPal'],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UpdateClientSecuritySettings([
'id' => 42,
'block_proxy' => true,
]);
```
#### Support Settings
patch/api/v1/admin/clients/{id}/support-settings
`Clients/UpdateClientSupportSettings` admin
Restricts or closes the client's ability to open support tickets.
Body 2
ticket_restrictedboolRestricts opening tickets.
ticket_blockedboolBlocks opening tickets outright.
Response fields data — 2
ticket_restrictedboolWhether opening tickets is restricted. The whole state comes back, not only the part you sent.
ticket_blockedboolWhether opening tickets is blocked.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/support-settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ticket_restricted":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/support-settings', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ticket_restricted: true }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/support-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['ticket_restricted' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UpdateClientSupportSettings([
'id' => 42,
'ticket_restricted' => true,
]);
```
### Pitfalls
> **Changing the password asks for no old one**
>
> The endpoint is an operator tool: it writes a new password without knowing the current one. The flow where a client changes their own password is a different one and lives in the Client API.
> **Verifying sends no code**
>
> `verify` only sets the flag; no email or SMS reaches the client. Call it **after** your own verification flow has run, not instead of it.
> **The two proxy fields are opposites**
>
> `block_proxy` blocks and `allow_proxy` exempts. Sending both as on leaves a contradictory state; send only the one you mean.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
## Signing In as a Client
https://dev.wisecp.com/en/client-sign-in
Hand a signed-in session to a client from your own system, without ever holding their password.
### Overview
Two endpoints cover the moment a client moves from your system into theirs.
- **POST /clients/validate**: Checks whether an email and password belong to a live client account. Your front end collects the credentials; this tells you which client is behind them.
- **POST /clients/sso**: Issues a one-time sign-in ticket and the URL that spends it. Send the client there and they arrive already signed in.
Use the second one when you already know who the visitor is: your own portal, a control panel, a desk tool. Use the first only when you are the one asking for the password.
### Prerequisites
- **Scopes**: `Clients/ValidateClient` and `Clients/CreateClientSsoToken`. Grant only the one you use.
- **Account state**: The client must be an active member account. Inactive or blocked accounts are refused when the ticket is issued.
- **HTTPS**: The ticket travels in a URL. Serve the redirect over HTTPS so it is not readable in transit.
### Structure
The ticket is a random secret, not a package of data. Everything the sign-in needs — the expiry and the landing page — is stored on the account, so nothing the caller receives can be edited into a different destination or a longer window.
- **Auth::createSsoToken()**: Issues the ticket, stores it encrypted on the account and returns the URL.
- **Auth::verifySsoToken()**: Resolves the ticket and consumes it before any session exists.
- **Auth::ssoLogin()**: Runs the normal sign-in gate, then opens the session.
### Step by Step
#### Sending a Client In
1. Your system decides which client this visitor is. Call `POST /clients/sso` with that client's id. You get back a `token`, a `url` and an `expires_at`.
2. Redirect the visitor to `url` straight away. Do not show it as a link for later — the ticket is valid for 60 seconds.
3. The visitor lands signed in, on their dashboard or on the page you named in `destination`. The ticket is spent; the same URL will not work twice.
#### Choosing Where They Land
1. Leave `destination` out and the client lands on their dashboard.
2. Send a route key with its parameters to land deeper: `"destination": "services", "destination_values": [128]`.
3. An absolute URL works too, as long as it belongs to this installation. Anything pointing elsewhere is dropped and the client lands on the dashboard instead.
### Reference
#### Ticket Request
- **client_id**: Required. The client to issue the ticket for. `user_id` is accepted as its former name.
- **destination**: Optional. A route key or an absolute URL inside this installation.
- **destination_values**: Optional. Route parameters, when `destination` is a route key.
#### How the Ticket Behaves
- **Single use**: Spent the moment the URL is opened. A replayed link lands on the sign-in form with an explanatory message.
- **Sixty seconds**: Issue it and follow it in one motion.
- **One per client**: A new ticket silently retires that client's previous one.
- **Sign-in gate**: Account status, country blocking and module vetoes are checked when the ticket is spent, as for a password sign-in.
Full field tables, error codes and response shapes are in the endpoint reference for `clients`.
### Example
Issue a ticket and redirect cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/sso' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"client_id":64,"destination":"services","destination_values":[128]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/sso', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
client_id: 64,
destination: 'services',
destination_values: [128],
}),
});
const body = await res.json();
// Redirect from the server that holds the key, not from the visitor's browser:
// the ticket is a credential and should not pass through untrusted code.
res.ok && console.log(body.data.url);
```
```php
true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['client_id' => 64]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
// Send the visitor there now; the ticket expires in 60 seconds.
header('Location: ' . $body['data']['url']);
exit;
```
```php
$response = Api::Clients()->CreateClientSsoToken([
'client_id' => 64,
'destination' => 'services',
'destination_values' => [128],
]);
// No key, no HTTP round trip — same resource, called in process.
Utility::redirect($response['data']['url']);
```
### Pitfalls
> **A ticket is a credential.** Whoever opens the URL becomes that client. Do not log it, email it or put it in a page a third party can read.
> **Do not mint tickets in advance.** They last 60 seconds and a client holds only one at a time, so issuing a batch leaves you with a single working ticket.
> **Validate does not sign anyone in.** It answers whether a password matches. If you want a session, issue a ticket afterwards.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Client Security Endpoints](https://dev.wisecp.com/en/client-security-endpoints)
## Client Endpoints
https://dev.wisecp.com/en/client-endpoints
The seven endpoints of the client resource: read, create, update, delete, plus credential checks and sign-in. Each one lists the fields you send, the fields you get back and a working sample.
### Overview
The client resource is the API side of the panel's **Clients** screen. It applies the same business rules. The password length and the email uniqueness you meet here are the ones the panel enforces, because the endpoint reuses the handler the panel calls.
All seven endpoints belong to the `admin` audience and expect the key to carry the matching scope. Scope names are written on each endpoint's identity line below.
> **The same endpoints are callable from inside WISECP**
>
> Writing a module or an addon? You do not have to go out over HTTP. `Api::Clients()->GetClients()` runs the same endpoint in process and returns **the same envelope**. The first tab of every sample shows that call.
### Reference
#### Listing Clients
get/api/v1/admin/clients
`Clients/GetClients` admin model `users::list`
Lists clients with filtering and pagination. Page size caps at 100; a larger value is quietly reduced.
Query parameters 5
searchstringSearches name and email.
statusstring`active` or `blocked`. Full list: `reference/statuses?entity=client`.
group_idintClient group id. List: `clients/groups`.
pageintDefaults to 1.
limitintDefaults to 25, maximum 100.
Response fields data[] — one client
idintClient id.
full_namestringFull name.
company_namestringCompany name; empty for an individual.
emailstringEmail address.
phonestringPhone; digits only are stored.
statusstring`active` or `blocked`.
groupobject 2 fieldsThe group this client belongs to.
idintGroup id.
namestringDisplay name.
languagestringLanguage code.
country_codestringISO country code, for example `US`.
currency_codestringCurrency code, for example `USD`.
email_verifiedboolWhether the email is verified.
phone_verifiedboolWhether the phone is verified.
active_servicesintNumber of services in use.
created_atstringCreation time.
last_login_atstringLast sign-in time.
Pagination meta
metaobject 4 fieldsIdentical on every list endpoint.
totalintTotal record count.
pageintCurrent page.
limitintPage size.
next_pageintNext page, or `0`.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients' \
-H "Authorization: Bearer $API_KEY" \
-H 'Accept: application/json' \
-d status=active \
-d limit=25
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients');
url.searchParams.set('status', 'active');
url.searchParams.set('limit', '25');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
for (const c of body.data) console.log(c.id, c.full_name);
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients?' . http_build_query([
'status' => 'active',
'limit' => 25,
]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Accept: application/json',
],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
foreach ($body['data'] as $client) {
echo $client['id'], ' ', $client['full_name'], PHP_EOL;
}
```
```php
// From inside WISECP: no HTTP, same envelope.
$response = Api::Clients()->GetClients([], [
'status' => 'active',
'limit' => 25,
]);
if (isset($response['error'])) {
Logger::error($response['error']['message']);
return;
}
foreach ($response['data'] as $client) {
echo $client['id'], ' ', $client['full_name'], PHP_EOL;
}
```
Response 200 403
```json
{
"data": [
{
"id": 42,
"full_name": "John Doe",
"company_name": "",
"email": "john@example.com",
"phone": "5550100",
"status": "active",
"group": { "id": 1, "name": "Standard" },
"email_verified": true,
"phone_verified": false,
"active_services": 3,
"created_at": "2026-01-01 10:00:00",
"last_login_at": "2026-06-20 09:00:00"
}
],
"meta": { "total": 128, "page": 1, "limit": 25, "next_page": 2 }
}
```
```json
{
"error": {
"code": "insufficient_scope",
"message": "API key lacks the required scope."
}
}
```
#### Client Detail
get/api/v1/admin/clients/{id}
`Clients/GetClient` admin model `users::get`
Returns one client's full profile. Fields the list does not carry arrive here: first and last name separately, the balance, and the country and currency ids.
Path parameter 1
idintrequiredClient id.
Response fields 15
idintClient id.
full_namestringFull name.
namestringFirst name. The list carries only `full_name`.
surnamestringLast name.
statusstring`active`, `blocked` or `cancelled`. The list never returns `cancelled`.
country_idintCountry id. Resolve with `reference/countries`.
currency_idintCurrency id.
group_idintClient group id. Where the list returns a `group` object, this returns the id only.
balancefloatAccount balance.
company_namestringCompany name.
emailstringEmail address.
phonestringPhone.
languagestringLanguage code.
created_atstringCreation time.
last_login_atstringLast sign-in time.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42' \
-H "Authorization: Bearer $API_KEY" \
-H 'Accept: application/json'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClient(['id' => 42]);
if (isset($response['error'])) {
// not_found or insufficient_scope
return false;
}
$client = $response['data'];
echo $client['name'], ' ', $client['surname'], PHP_EOL;
```
#### Creating a Client
post/api/v1/admin/clients
`Clients/CreateClient` admin same handler as the panel
Creates a client and returns the new record in the detail schema. Business rules run in the panel's own handler, so a setting such as password length applies here too.
Body 15 fields, 3 required
full_namestringrequiredFull name.
emailstringrequiredValidated for format and unique across every client in the installation.
passwordstringrequiredAt least `options/password-length` characters; defaults to 6.
typestring`individual` or `corporate`. Defaults to `individual`.
phonestringPhone. Digits are kept, formatting is dropped.
languagestringLanguage code. Defaults to `general/local`.
group_idintClient group. List: `clients/groups`.
country_codestringISO country code, for example `US`. Resolve with `reference/countries`.
currency_codestringCurrency code, for example `USD`.
companyobject 3 fieldsTax details for a corporate client.
namestringTrading name.
tax_numberstringTax number.
tax_officestringTax office.
identitystringIdentity or tax number.
marketing_notificationsboolTurns marketing notifications on.
verify_emailboolMarks the email as verified.
verify_phoneboolMarks the phone as verified.
send_welcome_emailboolSends the welcome email.
Response fields data — 15
dataobjectThe client that was created, returned with `201`. Same shape as the detail endpoint.
Errors 6
full_name_required422Full name was empty.
email_invalid422Email format is not valid.
email_exists422That email is already registered.
password_required422Password was empty.
create_failed500The record could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"full_name":"John Doe","email":"john@example.com","password":"Str0ngP@ssw0rd"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
full_name: 'John Doe',
email: 'john@example.com',
password: 'Str0ngP@ssw0rd',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'full_name' => 'John Doe',
'email' => 'john@example.com',
'password' => 'Str0ngP@ssw0rd',
]),
]);
$created = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClient([
'full_name' => 'John Doe',
'email' => 'john@example.com',
'password' => 'Str0ngP@ssw0rd',
'type' => 'individual',
'country_code' => 'US',
'currency_code' => 'USD',
]);
if (isset($response['error'])) {
// email_exists is the one you will meet most often.
throw new Exception($response['error']['message']);
}
$clientId = $response['data']['id'];
```
Response 201 422
```json
{
"data": {
"id": 43,
"full_name": "John Doe",
"name": "John",
"surname": "Doe",
"email": "john@example.com",
"status": "active",
"country_id": 840,
"currency_id": 2,
"group_id": 0,
"balance": 0.00
}
}
```
```json
{
"error": {
"code": "email_exists",
"message": "A client with this email already exists."
}
}
```
#### Updating a Client
patch/api/v1/admin/clients/{id}
`Clients/UpdateClient` admin partial update
Changes only the fields you send and leaves the rest alone. Every body field is optional.
Body 17 fields, all optional
full_namestringFull name. If sent, it cannot be empty.
emailstringValid and unique email.
statusstring`active`, `blocked` or `cancelled`.
phonestringMobile phone. Sending it empty clears it.
landline_phonestringLandline. Sending it empty clears it.
typestring`individual` or `corporate`.
identitystringIdentity or tax number.
birthdaystringDate of birth. An empty or invalid value clears the field.
languagestringLanguage code.
group_idintClient group.
currency_codestringCurrency code, for example `USD`.
companyobject 3 fieldsCorporate details.
namestringTrading name.
tax_numberstringTax number.
tax_officestringTax office.
billing flagsbool 5 fields`true` sets the flag, `false` clears it, leaving the field out changes nothing.
tax_exemptionboolExempts the client from tax.
never_suspendboolNever suspends the services.
never_cancelboolNever cancels the services.
separate_invoicesboolInvoices each service separately.
never_late_feeboolApplies no late fee.
Response fields data — 15
dataobjectThe client as it now stands. Same shape as the detail endpoint.
Errors 6
not_found404No such client.
full_name_required422Full name was sent empty.
email_invalid422Email format is not valid.
email_exists422That email is already in use.
phone_invalid422The phone number is not valid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"blocked","never_suspend":false}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: 'blocked', never_suspend: false }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'status' => 'blocked',
'never_suspend' => false,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Only two fields are sent; the rest of the profile stays as it was.
$response = Api::Clients()->UpdateClient([
'id' => 42,
'status' => 'blocked',
'never_suspend' => false,
]);
```
#### Deleting a Client
delete/api/v1/admin/clients/{id}
`Clients/DeleteClient` admin cannot be undone
Deletes the client and returns the id that was removed.
Response fields data
deletedboolWhether the delete succeeded.
idintId of the deleted client.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClient(['id' => 42]);
if (($response['data']['deleted'] ?? false) === true) {
// The record is gone; clear your own data that pointed at it.
}
```
#### Validating Client Credentials
post/api/v1/admin/clients/validate
`Clients/ValidateClient` admin writes nothing
Answers one question: do this email and password belong to a live member account? Nothing is created or changed. Use it when your own front end holds the credentials and needs the client id behind them.
> **The stored password never comes back**
>
> It is a bcrypt digest wrapped in the installation's own encryption. Returning it would let any holder of an admin key verify guesses offline. The response carries the client id and nothing else.
Body 2 fields, both required
emailstringrequiredThe account's email address.
passwordstringrequiredThe password to check.
Response fields data — 2
validboolAlways `true`. A mismatch comes back as an error, not as `valid: false`.
user_idintThe client the credentials belong to.
Errors 3
credentials_required422`email` or `password` is missing.
invalid_credentials422No live member account matches this pair.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/validate' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"email":"john@example.com","password":"correct horse battery staple"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/validate', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ email: 'john@example.com', password }),
});
if (res.ok) {
const body = await res.json();
console.log(body.data.user_id); // the client behind the credentials
}
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/validate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'email' => 'john@example.com',
'password' => $password,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->ValidateClient([
'email' => 'john@example.com',
'password' => $password,
]);
// A wrong pair arrives as an error, so reaching this line already means they matched.
$clientId = $response['data']['user_id'] ?? 0;
```
#### Signing In as a Client
post/api/v1/admin/clients/sso
`Clients/CreateClientSsoToken` admin single use, 60 seconds
Issues a one-time sign-in ticket for a client and returns the URL that spends it. Send the client to that URL and they arrive already signed in. Your integration never handles their password.
Intended for a system that already knows who the visitor is: your own portal, a control panel, a desk tool. `login_as_client` is not exposed over the API because it swaps the PHP session in place; this endpoint is its token-based equivalent.
> **How the ticket behaves**
>
> **Single use** — it is spent the moment the URL is opened. A replayed link lands on the sign-in form with an explanatory message. **Valid for 60 seconds**, meant to be issued and followed in one motion. **One per client**: a new ticket silently retires the previous one. **Confined to this installation**, so a `destination` pointing anywhere else is dropped and the client lands on their dashboard. **The login gate still applies.** Account status, country blocking and module vetoes are evaluated when the ticket is spent, exactly as for a password login. The ticket proves *who*, not *whether they may sign in right now*.
Body 3 fields, 1 required
client_idintrequiredClient to issue the ticket for. `user_id` is still accepted as its former name.
destinationstringWhere the client lands after signing in: an absolute URL on this installation, or a route key such as `services`. Defaults to their dashboard.
destination_valuesarrayRoute parameters, when `destination` is a route key.
Response fields data — 3
tokenstringThe ticket, in the form `{client_id}-{secret}`.
urlstringSign-in URL carrying the ticket; send the client here.
expires_atstringExpiry, ISO 8601 with offset.
Errors 5
client_id_required422`client_id` is missing.
client_not_found404No client with this id.
client_not_active422The account is inactive, blocked or otherwise cannot sign in.
sso_ticket_failed422The key could not be issued.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/sso' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"client_id":42,"destination":"services","destination_values":[128]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/sso', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ client_id: 42, destination: 'services', destination_values: [128] }),
});
const body = await res.json();
window.location = body.data.url; // spend it now; it lasts 60 seconds
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/sso');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'client_id' => 42,
'destination' => 'services',
'destination_values' => [128],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClientSsoToken(['client_id' => 42]);
$link = $response['data']['url'];
```
### Pitfalls
> **List and detail do not share a schema**
>
> The list returns the group as an object (`group`). The detail returns the id alone (`group_id`). The name is one field in the list and two in the detail. A mapper written against the list quietly produces empty fields when it meets the detail.
> **On update an empty value means delete**
>
> Sending an empty phone or birthday **clears** the field. To keep a field, leave it out of the body entirely; that is what a partial update is for.
> **A phone is not stored the way you write it**
>
> Formatting is dropped and only digits remain. Send `+1 555 010 0000` and you read back `15550100000`; any code that compares the two has to account for it.
### Related Articles
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [API Resource Map](https://dev.wisecp.com/en/api-resources)
## Stored Cards
https://dev.wisecp.com/en/stored-cards
The three endpoints that read a client's stored cards, pick the default and delete one.
### Overview
A stored card is a card held at the client's payment provider. WISECP does **not** keep the card number; it holds a token from the provider and enough to recognise the card — the last four digits, the brand, the expiry.
That is why there is no endpoint here that *adds* a card. A card is stored on the provider's own screen while the client pays; the API only reads what exists, moves the default and deletes.
### Reference
#### Listing Cards
get/api/v1/admin/clients/{id}/cards
`Clients/GetClientCards` admin
Returns the client's stored cards. The card number never comes back; only the last four digits show.
Response fields data[] — 6
idintId of the stored card.
last4stringThe last four digits of the card number.
brandstringCard brand, for example `visa` or `mastercard`.
modulestringThe payment module holding the card, for example `Stripe`.
is_defaultboolWhether this is the default card.
expirystringExpiry date, in `12/27` form.
Errors 2
not_found404No such client or card.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/cards' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/cards', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
const primary = body.data.find((card) => card.is_default);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/cards');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientCards(['id' => 42]);
foreach ($response['data'] as $card) {
if ($card['is_default']) {
$primary = $card;
}
}
```
Response 200
```json
{
"data": [
{
"id": 88,
"last4": "4242",
"brand": "visa",
"module": "Stripe",
"is_default": true,
"expiry": "12/27"
}
]
}
```
#### Setting the Default Card
put/api/v1/admin/clients/{id}/cards/{card_id}/default
`Clients/SetClientCardDefault` admin
Makes a card the default. The flag on the previous one clears by itself.
Body —
——No body is needed; send an empty one. Both the client and the card come from the path.
——There is no way to clear the default without another card taking its place.
Response fields data — 2
card_idintId of the card that became the default.
defaultboolAlways `true`.
Errors 2
not_found404No such client or card.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/cards/88/default' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/cards/88/default', {
method: 'PUT',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/cards/88/default');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SetClientCardDefault([
'id' => 42,
'card_id' => 88,
]);
```
#### Deleting a Card
delete/api/v1/admin/clients/{id}/cards/{card_id}
`Clients/DeleteClientCard` admin may move the default
Deletes the stored card. If it was the default, another one takes its place and the id comes back in the response.
Response fields data — 3
deletedboolWhether the delete succeeded.
card_idintId of the deleted card.
new_default_idintId of the new default card. `0` when the deleted card was not the default.
Errors 2
not_found404No such client or card.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/cards/88' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/cards/88', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
if (body.data.new_default_id) {
// The default moved to another card.
}
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/cards/88');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientCard([
'id' => 42,
'card_id' => 88,
]);
$newDefault = $response['data']['new_default_id'] ?? 0;
```
### Pitfalls
> **There is no endpoint that adds a card**
>
> A card can only be stored during the client's payment flow, because the number is entered at the provider. An integration trying to add one through the API is looking for an endpoint that does not exist.
> **Deleting can move the default**
>
> Delete the default card and another takes its place; its id comes back in `new_default_id`. If you keep the default on your side, read that value and update it.
> **What you see is not the card number**
>
> `last4` is only there to recognise the card. The API never returns the card number, the full expiry or the security code on any endpoint.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
## Document Scheme
https://dev.wisecp.com/en/document-scheme
The ten endpoints that define which document is asked of whom: the field pool and the filters that use it.
### Overview
The document scheme has two layers. **Fields** are a shared pool — single inputs such as "passport copy" or "tax certificate". **Filters** pick a set out of that pool and carry the rules that decide *who* is asked for it.
One field can sit in several filters; that is what the pool is for. Updating a field reaches every filter using it at once.
### Reference
#### Listing Filters
get/api/v1/admin/clients/document-filters
`Clients/GetDocumentFilters` admin
Returns the document filters. Each one carries a set of fields and the rules that decide who is asked for them.
Query parameters 3
statusstring`active` or `inactive`.
pageintDefaults to 1.
limitintDefaults to 25, maximum 100.
Response fields data[] — 5
idintFilter id.
namestringFilter name.
statusstring`active` or `inactive`.
fieldsint[]An **ordered** list of ids from the field pool. The order is what the client sees.
rulesobject[] 3 fieldsThe rules that decide who the filter applies to.
typestringWhat the rule looks at: `email_provider`, `vpn_proxy`, `account_age`, `service_count`, `total_spending`, `country_mismatch`, `country`.
valuestringDepends on the type: a list of domains, `yes`, a numeric threshold or a country id.
extrastringAn extra value for some types. Empty on most rules.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients/document-filters' \
-H "Authorization: Bearer $API_KEY" \
-d status=active
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients/document-filters');
url.searchParams.set('status', 'active');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients/document-filters?' . http_build_query(['status' => 'active']);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetDocumentFilters([], ['status' => 'active']);
```
#### Adding a Filter
post/api/v1/admin/clients/document-filters
`Clients/CreateDocumentFilter` admin
Defines a new filter. The field ids have to exist in the pool.
Body 4
namestringrequiredFilter name.
fieldsint[]requiredOrdered field ids, for example `[3, 1]`.
activeboolDefaults to `false`; the filter is born `inactive`.
rulesobject[] 3 fieldsThe rules that apply it.
typestringWhat the rule looks at: `email_provider`, `vpn_proxy`, `account_age`, `service_count`, `total_spending`, `country_mismatch`, `country`.
valuestringDepends on the type: a list of domains, `yes`, a numeric threshold or a country id.
extrastringAn extra value for some types. Empty on most rules.
Response fields data — 5
idintId of the new filter.
namestringFilter name.
statusstring`active` or `inactive`. A new filter is born inactive unless you sent `active`.
fieldsint[]The ordered field ids, as stored.
rulesobject[]The stored rules — same `type` / `value` / `extra` shape as the listing.
Errors 5
name_required422`name` was empty.
fields_required422`fields` was empty or malformed.
fields_invalid422None of the ids exist in the field pool.
filter_add_failed500The record could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/document-filters' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"High spend","fields":[3,1],"active":true,"rules":[{"type":"total_spending","value":"5000","extra":""}]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-filters', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({"name":"High spend","fields":[3,1],"active":true,"rules":[{"type":"total_spending","value":"5000","extra":""}]}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-filters');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'High spend',
'fields' => [3, 1],
'active' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateDocumentFilter([
'name' => 'High spend',
'fields' => [3, 1],
'active' => true,
'rules' => [
['type' => 'total_spending', 'value' => '5000', 'extra' => ''],
],
]);
```
#### Filter Detail
get/api/v1/admin/clients/document-filters/{fid}
`Clients/GetDocumentFilter` admin
Returns one filter; the schema is the same as in the list.
Response fields data — 5
idintFilter id.
namestringFilter name.
statusstring`active` or `inactive`.
fieldsint[]The ordered field ids, exactly as the listing returns them.
rulesobject[]The rules, same `type` / `value` / `extra` shape as the listing.
Errors 2
not_found404No such record.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/document-filters/7' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-filters/7', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-filters/7');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetDocumentFilter(['fid' => 7]);
```
#### Updating a Filter
patch/api/v1/admin/clients/document-filters/{fid}
`Clients/UpdateDocumentFilter` admin
Changes the filter name, the field order, the status or the rules.
Body at least one
namestringFilter name.
fieldsint[]The new ordered field list. What you send replaces the old list.
activeboolTurns the filter on or off.
rulesobject[]The new rule list. This replaces as well, it does not append.
Response fields data — 5
idintFilter id.
namestringFilter name after the update.
statusstring`active` or `inactive`.
fieldsint[]The stored field order — read it back to see what the replace actually left.
rulesobject[]The stored rules; an empty array means the filter now applies to everyone.
Errors 5
not_found404No such filter.
name_required422`name` was sent empty.
fields_required422`fields` was sent empty or malformed.
fields_invalid422An id does not exist in the field pool.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/document-filters/7' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"active":false}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-filters/7', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ active: false }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-filters/7');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['active' => false]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UpdateDocumentFilter([
'fid' => 7,
'active' => false,
]);
```
#### Deleting a Filter
delete/api/v1/admin/clients/document-filters/{fid}
`Clients/DeleteDocumentFilter` admin
Deletes the filter. The field pool is untouched; the fields stay in whatever other filters use them.
Response fields data — 2
deletedboolWhether the delete succeeded.
idintId of the deleted filter.
Errors 1
not_found404No such filter.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/document-filters/7' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-filters/7', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-filters/7');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteDocumentFilter(['fid' => 7]);
```
#### Listing Fields
get/api/v1/admin/clients/document-fields
`Clients/GetDocumentFields` admin
Returns the shared field pool. Filters pick their fields from here.
Query parameters 4
statusstring`active` or `inactive`.
pageintDefaults to 1.
limitintDefaults to 25, maximum 100.
typestringFilters by input type.
Response fields data[] — 8
idintField id. A filter's `fields` list points here.
statusstring`active` or `inactive`. An inactive field is not shown to the client.
typestring`input`, `textarea`, `selectbox`, `radio`, `checkbox`, `file`.
labelsobjectLabel per language, for example `{"en": "Passport copy"}`.
optionsobjectOptions per language. Only meaningful on the choice types.
allowed_extstringAllowed file extensions. Only on the `file` type.
max_sizeintMaximum file size in MB. Only on the `file` type.
used_inobject[]The filters using this field: `[{ id, name }]`.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients/document-fields' \
-H "Authorization: Bearer $API_KEY" \
-d type=file
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients/document-fields');
url.searchParams.set('type', 'file');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients/document-fields?' . http_build_query(['type' => 'file']);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetDocumentFields([], ['type' => 'file']);
```
#### Adding a Field
post/api/v1/admin/clients/document-fields
`Clients/CreateDocumentField` admin
Adds a field to the pool. The label has to be given in at least one language.
Body 6
typestringrequiredInput type.
labelsobjectrequiredLabel per language; at least one.
activeboolDefaults to `true`.
optionsobjectOptions per language. In practice required on the choice types.
allowed_extstringAllowed extensions. Only on the `file` type.
max_sizeintLimit in MB. Only on the `file` type.
Response fields data — 7
idintId of the new field.
statusstring`active` or `inactive`.
typestringThe stored input type.
labelsobjectThe stored labels, per language.
optionsobjectThe stored choices, per language.
allowed_extstringAllowed file extensions.
max_sizeintMaximum file size in MB.
used_in—Not part of this answer: a newly created field belongs to no filter yet.
Errors 4
type_invalid422`type` is not one of the allowed input types.
labels_required422No language carried a non-empty label.
field_add_failed500The record could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/document-fields' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"file","labels":{"en":"Passport copy"},"allowed_ext":"jpg,png,pdf","max_size":5}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-fields', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'file',
labels: {"en":"Passport copy"},
allowed_ext: 'jpg,png,pdf',
max_size: 5,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-fields');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'type' => 'file',
'labels' => ['en' => 'Passport copy'],
'allowed_ext' => 'jpg,png,pdf',
'max_size' => 5,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateDocumentField([
'type' => 'file',
'labels' => ['en' => 'Passport copy'],
'allowed_ext' => 'jpg,png,pdf',
'max_size' => 5,
]);
```
#### Field Detail
get/api/v1/admin/clients/document-fields/{fid}
`Clients/GetDocumentField` admin
Returns one field. `used_in` comes with it, showing which filters use it.
Response fields data — 8
idintField id — this is what a filter's `fields` list refers to.
statusstring`active` or `inactive`. An inactive field is not shown to clients even where a filter still lists it.
typestringInput type: `input`, `textarea`, `selectbox`, `radio`, `checkbox`, `file`.
labelsobjectThe label per language, for example `{ "en": "Passport copy" }`.
optionsobjectPer-language choices for the list types. Empty on the other types.
allowed_extstringAllowed file extensions — `file` type only.
max_sizeintMaximum file size in MB — `file` type only.
used_inobject[]The filters referencing this field, as `{ id, name }`. Read it before deleting — every one of them loses the field.
Errors 2
not_found404No such field.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/document-fields/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-fields/3', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-fields/3');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetDocumentField(['fid' => 3]);
// Before deleting: which filters hold this field?
$usedIn = $response['data']['used_in'] ?? [];
```
#### Updating a Field
patch/api/v1/admin/clients/document-fields/{fid}
`Clients/UpdateDocumentField` admin
Updates the field. The change reaches every filter using it at once.
Body 6
typestringrequiredInput type. Required even on an update — this endpoint rewrites the field rather than patching single keys.
labelsobjectrequiredLabel per language; at least one must be non-empty.
activeboolTurns the field on or off. Defaults to `true`.
optionsobjectChoices per language. In practice required on the choice types.
allowed_extstringAllowed extensions. Only on the `file` type.
max_sizeintLimit in MB. Only on the `file` type.
Response fields data — 7
idintField id.
statusstring`active` or `inactive`.
typestringThe stored input type.
labelsobjectThe stored labels, per language.
optionsobjectThe stored choices, per language.
allowed_extstringAllowed file extensions.
max_sizeintMaximum file size in MB.
Errors 4
not_found404No such field.
type_invalid422`type` is not one of the allowed input types.
labels_required422No language carried a non-empty label.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/document-fields/3' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"max_size":10}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-fields/3', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ max_size: 10 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-fields/3');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['max_size' => 10]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UpdateDocumentField([
'fid' => 3,
'max_size' => 10,
]);
```
#### Deleting a Field
delete/api/v1/admin/clients/document-fields/{fid}
`Clients/DeleteDocumentField` admin affects filters
Removes the field from the pool.
Response fields data — 2
deletedboolWhether the delete succeeded.
idintId of the deleted field.
Errors 1
not_found404No such field.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/document-fields/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-fields/3', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-fields/3');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteDocumentField(['fid' => 3]);
```
### Pitfalls
> **The field list is ordered**
>
> `fields` is not a set but an **ordered** list, and the client sees the fields in that order. On update the list you send replaces the old one; it does not append to it.
> **A field is shared, not copied**
>
> Updating or deleting a field affects **every** filter that uses it. Look at `used_in` on the field detail before you delete.
> **A new filter is born switched off**
>
> Leave `active` out and the filter is created as `inactive`, asking nobody for anything. Creating one and walking away leaves a verification that never runs.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
## Client Documents
https://dev.wisecp.com/en/client-documents
The six endpoints that read a client's submitted documents, approve or reject them, and manage the canned rejection reasons.
### Overview
A client fills in the fields the document scheme asks for and submits them; these endpoints read those submissions and settle them. The scheme itself is a separate job and lives in **Document Scheme**.
Each record maps to one field and carries its own status. A client can have some documents approved while others are still waiting.
### Reference
#### Fetching Documents
get/api/v1/admin/clients/{id}/documents
`Clients/GetClientDocuments` admin marks as read
Returns the document records the client submitted. Records hang off the field id and every filter is merged into one list.
Query parameter 1
filter_idintIf given, the list narrows to the records that came from that filter.
Response fields data — 2
filtersobject[]The filters the returned records came from: `[{ id, name }]`.
recordsobject[] 8 fieldsThe document records.
idintId of the document record. This is the key you use in the review request.
field_keyintId of the field in the shared pool.
field_namestringThe field label. Refreshed from the pool; if the field was deleted, the copy taken at submission comes back.
field_typestringInput type: `input`, `textarea`, `selectbox`, `radio`, `checkbox`, `file`.
field_valuestringThe value the client submitted. On file fields, JSON carrying the upload identifier.
filter_idintThe filter this record came from.
statusstring`awaiting`, `verified` or `unverified`.
status_msgstringThe review note; a rejection reason goes here.
Errors 2
not_found404No such client or record.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/documents' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/documents', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
const waiting = body.data.records.filter((r) => r.status === 'awaiting');
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/documents');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientDocuments(['id' => 42]);
$waiting = [];
foreach ($response['data']['records'] as $record) {
if ($record['status'] === 'awaiting') {
$waiting[] = $record['id'];
}
}
```
#### Reviewing Documents
patch/api/v1/admin/clients/{id}/documents
`Clients/ReviewClientDocuments` admin notifies the client
Updates the verification status of several records at once. Every record whose status changes sends the client a notification.
Body 1
statusesobjectrequired 2 fieldsA map keyed by record id: `{"": {"status": …, "message": …}}`.
statusstringrequired`verified`, `unverified` or `awaiting`. A record carrying anything else is skipped in silence.
messagestringThe review note. Put the reason here when rejecting; the client sees it.
Response fields data — 3
reviewedboolWhether the review was processed.
verifiedintHow many records were approved.
rejectedintHow many records were rejected.
Errors 2
not_found404No such client, or the client has no records at all.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/documents' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"statuses":{"51":{"status":"verified"},"52":{"status":"unverified","message":"The document is unreadable, please send a clearer copy"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/documents', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
statuses: {
51: { status: 'verified' },
52: { status: 'unverified', message: 'The document is unreadable, please send a clearer copy' },
},
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/documents');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'statuses' => [
51 => ['status' => 'verified'],
52 => ['status' => 'unverified', 'message' => 'The document is unreadable, please send a clearer copy'],
],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->ReviewClientDocuments([
'id' => 42,
'statuses' => [
51 => ['status' => 'verified'],
52 => ['status' => 'unverified', 'message' => 'The document is unreadable, please send a clearer copy'],
],
]);
$rejected = $response['data']['rejected'] ?? 0;
```
Response 200
```json
{
"data": {
"reviewed": true,
"verified": 1,
"rejected": 1
}
}
```
#### Deleting a Document Record
delete/api/v1/admin/clients/{id}/documents/{record_id}
`Clients/DeleteClientDocument` admin
Deletes a single document record.
Response fields data — 2
deletedboolWhether the delete succeeded.
idintId of the deleted record.
Errors 3
not_found404No such client.
record_required422The record id was missing.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/documents/51' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/documents/51', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/documents/51');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientDocument([
'id' => 42,
'record_id' => 51,
]);
```
#### Listing Rejection Reasons
get/api/v1/admin/clients/document-rejection-reasons
`Clients/GetDocumentRejectionReasons` admin
Returns the saved rejection reasons. These are the canned texts used while reviewing.
Response fields data[]
datastring[]A plain list of reason texts — there are no ids here, the text itself is the identity.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/document-rejection-reasons' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-rejection-reasons', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-rejection-reasons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetDocumentRejectionReasons();
```
#### Adding a Rejection Reason
post/api/v1/admin/clients/document-rejection-reasons
`Clients/AddDocumentRejectionReason` admin
Adds a new canned reason to the list.
Body 1
valuestringrequiredThe reason text.
Response fields data[]
datastring[]The whole list after the add, not the added text alone.
Errors 2
value_required422`value` was empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/document-rejection-reasons' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"value":"The document is unreadable, please send a clearer copy"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-rejection-reasons', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ value: 'The document is unreadable, please send a clearer copy' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-rejection-reasons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['value' => 'The document is unreadable, please send a clearer copy']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->AddDocumentRejectionReason(['value' => 'The document is unreadable, please send a clearer copy']);
```
#### Deleting a Rejection Reason
delete/api/v1/admin/clients/document-rejection-reasons
`Clients/DeleteDocumentRejectionReason` admin deleted by text
Removes a reason from the list. You send the text itself, not an id.
Body 1
valuestringrequiredThe text of the reason to remove. It has to match the stored one exactly.
Response fields data[]
datastring[]The reasons that remain. A text that did not match leaves the list unchanged — compare it to know whether anything went.
Errors 2
value_required422`value` was empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/document-rejection-reasons' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"value":"The document is unreadable, please send a clearer copy"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/document-rejection-reasons', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ value: 'The document is unreadable, please send a clearer copy' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/document-rejection-reasons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['value' => 'The document is unreadable, please send a clearer copy']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteDocumentRejectionReason(['value' => 'The document is unreadable, please send a clearer copy']);
```
### Pitfalls
> **Listing marks the records as read**
>
> The fetch endpoint is not read-only: calling it marks the records as read. An integration polling this while watching the pending-document badge will clear that badge on every poll.
> **A review notifies the client**
>
> Every record whose status changes sends an approval or rejection notice. Sending the same status twice counts as no change, but rejecting a record by mistake and fixing it produces **two** notices.
> **A rejection reason is deleted by its text**
>
> The delete request takes `value`, not an id, and the text has to match exactly. Even one space of difference will not find the record.
### Related Articles
- [Document Scheme](https://dev.wisecp.com/en/document-scheme)
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
## GDPR Requests
https://dev.wisecp.com/en/gdpr-requests
The ten endpoints that read a client's data removal requests, settle them, and manage the feature's settings.
### Overview
A client can ask for their data to be removed. These endpoints read those requests, settle them, and manage the feature's own settings.
Removal has three scopes and **no way back**: cutting access, anonymising the identifying data, deleting the user outright. Which one ran is in `remove_action` on the response.
### Reference
#### Listing Requests
get/api/v1/admin/clients/gdpr-requests
`Clients/GetGdprRequests` admin
Returns the list of data requests coming from clients.
Query parameters 4
statusstringFilters by status.
typestringFilters by request type.
pageintDefaults to 1.
limitintDefaults to 25, maximum 100.
Response fields data[] — 5
idintRequest id.
user_idintThe client who asked.
typestringWhat was asked for, for example `remove`.
statusstringWhere the request stands, for example `pending`.
created_atstringWhen it arrived.
Meta 4
totalintTotal matching requests.
pageintThe page you are on.
limitintPage size.
next_pageintThe next page, or `0` on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients/gdpr-requests' \
-H "Authorization: Bearer $API_KEY" \
-d limit=50
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients/gdpr-requests');
url.searchParams.set('limit', '50');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients/gdpr-requests?' . http_build_query(['limit' => 50]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetGdprRequests([], ['limit' => 50]);
```
#### Request Detail
get/api/v1/admin/clients/gdpr-requests/{rid}
`Clients/GetGdprRequest` admin
Returns one request. This is what you read before deciding.
Response fields data — 1
requestobject 7 fieldsThe request record.
idintRequest id.
statusstringStatus of the request.
remove_typestringThe scope asked for: `block_access`, `identifying_data` or `all`.
invoice_countintHow many invoices the client has. Worth reading before deciding: invoices fall under legal retention.
processedboolWhether it has been settled.
processed_byintId of the admin who settled it.
created_atstringWhen the request arrived.
Errors 2
not_found404No such request.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/gdpr-requests/9' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-requests/9', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-requests/9');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetGdprRequest(['rid' => 9]);
$request = $response['data']['request'];
// Asking for 'all' on a client with invoices can collide with legal retention.
$hasInvoices = $request['invoice_count'] > 0;
```
#### Settling a Request
post/api/v1/admin/clients/gdpr-requests/{rid}/process
`Clients/ProcessGdprRequest` admin cannot be undone
Approves or refuses the request. On approval the data removal runs in the scope you choose.
Body 5
statusstringrequiredThe decision: `remove`, `anonymize`, `destroy`, or `cancelled` to refuse.
remove_typestringThe removal scope. Only meaningful when approving. `block_access` cuts access, `identifying_data` anonymises the identifying data, `all` deletes the user.
status_notestringA note on the decision. Put the reason here when refusing.
notificationboolSends the client a notification.
blacklistboolBlacklists or unblacklists the client in the same operation.
Response fields data — 4
processedboolWhether it was settled.
statusstringThe status that was applied.
remove_actionstringThe removal that actually ran: `none`, `block_access`, `identifying_data` or `all`.
blacklistintBlacklist state afterwards: `0` or `1`.
Errors 4
not_found404No such request.
status_invalid422`status` is not one of the allowed values.
blocked_by_gate422A hook vetoed the operation. One of your own addons may be blocking the removal.
gdpr_delete_failed500The user data could not be removed.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/gdpr-requests/9/process' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"anonymize","remove_type":"identifying_data","status_note":"Request verified","notification":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-requests/9/process', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
status: 'anonymize',
remove_type: 'identifying_data',
status_note: 'Request verified',
notification: true,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-requests/9/process');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'status' => 'anonymize',
'remove_type' => 'identifying_data',
'status_note' => 'Request verified',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->ProcessGdprRequest([
'rid' => 9,
'status' => 'anonymize',
'remove_type' => 'identifying_data',
'status_note' => 'Request verified',
]);
$applied = $response['data']['remove_action'] ?? 'none';
```
Response 200 422
```json
{
"data": {
"processed": true,
"status": "anonymize",
"remove_action": "identifying_data",
"blacklist": 0
}
}
```
```json
{
"error": {
"code": "blocked_by_gate",
"message": "The removal was blocked by a hook."
}
}
```
#### Deleting a Request
delete/api/v1/admin/clients/gdpr-requests/{rid}
`Clients/DeleteGdprRequest` admin
Deletes the request record. It does not touch the client's data; only the record goes.
Response fields data — 2
deletedboolWhether the delete succeeded.
idintId of the deleted request.
Errors 1
not_found404No such request.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/gdpr-requests/9' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-requests/9', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-requests/9');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteGdprRequest(['rid' => 9]);
```
#### Reading the Settings
get/api/v1/admin/clients/gdpr-settings
`Clients/GetGdprSettings` admin
Returns whether the feature is on, which contract page is attached, and the canned denial reasons.
Response fields data — 4
enabledboolWhether the feature is on.
requiredboolWhether consent is mandatory.
contract_page_idintId of the attached contract page.
denial_reasonsarrayThe canned denial reasons. An empty array when there are none.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/gdpr-settings' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-settings', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetGdprSettings();
```
#### Saving the Settings
put/api/v1/admin/clients/gdpr-settings
`Clients/SaveGdprSettings` admin
Turns the feature on or off and attaches the contract page.
Body 3
enabledboolTurns the feature on or off.
requiredboolMakes consent mandatory.
contract_page_idintId of the contract page to attach. List: `gdpr-contracts`.
Response fields data — 3
enabledboolWhether the feature is on after the write.
requiredboolWhether consent is mandatory.
contract_page_idintThe attached contract page.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/gdpr-settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true,"required":true,"contract_page_id":12}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-settings', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: true, required: true, contract_page_id: 12 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'enabled' => true,
'required' => true,
'contract_page_id' => 12,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SaveGdprSettings([
'enabled' => true,
'required' => true,
'contract_page_id' => 12,
]);
```
#### Searching Contract Pages
get/api/v1/admin/clients/gdpr-contracts
`Clients/GetGdprContracts` admin
Returns the pages that can be attached as the contract. This is where `contract_page_id` comes from.
Response fields data[] — 2
idintPage id — this is what you send as `contract_page_id`.
titlestringPage title.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/gdpr-contracts' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-contracts', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-contracts');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetGdprContracts();
```
#### Listing Denial Reasons
get/api/v1/admin/clients/gdpr-denial-reasons
`Clients/GetGdprDenialReasons` admin
Returns the canned texts used when refusing a request.
Response fields data[]
datastring[]A plain list of reason texts — there are no ids here, the text itself is the identity.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetGdprDenialReasons();
```
#### Adding a Denial Reason
post/api/v1/admin/clients/gdpr-denial-reasons
`Clients/AddGdprDenialReason` admin
Adds a new canned reason to the list.
Body 1
valuestringrequiredThe reason text.
Response fields data[]
datastring[]The whole list after the add, not the added text alone.
Errors 1
value_required422`value` was empty.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"value":"The legal retention period has not ended"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ value: 'The legal retention period has not ended' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['value' => 'The legal retention period has not ended']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->AddGdprDenialReason(['value' => 'The legal retention period has not ended']);
```
#### Deleting a Denial Reason
delete/api/v1/admin/clients/gdpr-denial-reasons
`Clients/DeleteGdprDenialReason` admin deleted by text
Removes a reason from the list. You send the text itself, not an id.
Body 1
valuestringrequiredThe text to remove. It has to match the stored one exactly.
Response fields data[]
datastring[]The reasons that remain. A text that did not match leaves the list unchanged — compare it to know whether anything went.
Errors 1
value_required422`value` was empty.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"value":"The legal retention period has not ended"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ value: 'The legal retention period has not ended' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/gdpr-denial-reasons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['value' => 'The legal retention period has not ended']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteGdprDenialReason(['value' => 'The legal retention period has not ended']);
```
### Pitfalls
> **Read the invoice count before deciding**
>
> The request detail carries `invoice_count`. In most countries invoices fall under a legal retention period, so asking for `all` on a client with invoices can collide with that duty. That is why the field is in the response.
> **A hook can veto the operation**
>
> A `blocked_by_gate` error does not mean your request was wrong; it means an addon in the installation blocked the removal. If you wrote your own hook, look there first.
> **Deleting the request does not delete the data**
>
> The delete endpoint only removes the request record. The client's data stays exactly as it was; removal runs only through the process endpoint.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Blacklist and Duplicates](https://dev.wisecp.com/en/blacklist-and-duplicates)
## Affiliate
https://dev.wisecp.com/en/affiliate-endpoints
The nine endpoints that open an affiliate partnership, set the commission, run the payout and scan for suspicious referrals.
### Overview
In an affiliate partnership a client earns commission on every sale they bring. These endpoints open the partnership, set the commission rule, run the payout and scan for suspicious referrals.
Commission has two periods: `lifetime` pays on every renewal the referred client makes, `onetime` only on the first sale. The choice is per partner.
### Reference
#### Reading the Affiliate Status
get/api/v1/admin/clients/{id}/affiliate
`Clients/GetClientAffiliate` admin
Returns the client's affiliate status, commission settings and balance.
Response fields data — 8
is_affiliateboolWhether the client is an affiliate.
activated_atdatetimeWhen the partnership was opened.
disabledboolWhether the partnership is switched off.
disabled_reasonstringWhy it was switched off.
commission_valuefloatCommission rate as a percentage. Between 0 and 100.
commission_periodstring`lifetime` pays on every renewal, `onetime` only on the first sale. An empty value uses the default.
balancefloatThe partner's earnings balance.
currency_idintCurrency id of the balance.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/affiliate' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/affiliate', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/affiliate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientAffiliate(['id' => 42]);
if (!($response['data']['is_affiliate'] ?? false)) {
return;
}
```
#### Opening the Partnership
post/api/v1/admin/clients/{id}/affiliate
`Clients/ActivateClientAffiliate` admin
Makes the client an affiliate. On a client who already is one, it returns an error.
Body 3
commission_valuenumberCommission rate. Clamped to 0-100; a value outside that is not refused, it is trimmed.
commission_periodstring`lifetime` or `onetime`. Anything else becomes empty.
currency_idintBalance currency. List: `reference/currencies`.
Response fields data
dataobjectThe partnership opened, returned with `201`. Same shape as the status endpoint.
Errors 4
not_found404No such client.
already_affiliate422The client is already an affiliate.
activate_failed500The partnership could not be opened.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/affiliate' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"commission_value":10,"commission_period":"lifetime","currency_id":1}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/affiliate', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
commission_value: 10,
commission_period: 'lifetime',
currency_id: 1,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/affiliate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'commission_value' => 10,
'commission_period' => 'lifetime',
'currency_id' => 1,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->ActivateClientAffiliate([
'id' => 42,
'commission_value' => 10,
'commission_period' => 'lifetime',
'currency_id' => 1,
]);
```
#### Updating the Partnership
patch/api/v1/admin/clients/{id}/affiliate
`Clients/UpdateClientAffiliate` admin blocking lives here
Changes the commission, the balance and the partner's state. Blocking goes through here too.
Body 7
commission_valuenumberCommission rate; clamped to 0-100.
commission_periodstring`lifetime` ya da `onetime`.
currency_idintBalance currency.
balancenumberThe partner's balance. A negative value is pulled up to zero.
disabledboolSwitches the partnership off or back on.
disabled_reasonstringWhy it was switched off. Only written while `disabled` is on.
block_partnerboolBlocks the partner **and cancels the waiting withdrawal requests**.
Response fields data
dataobjectThe partnership as it now stands. Same shape as the status endpoint.
Errors 3
not_found404No such client.
not_affiliate422The client is not an affiliate.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/affiliate' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"commission_value":15}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/affiliate', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ commission_value: 15 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/affiliate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['commission_value' => 15]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Blocking also cancels the waiting withdrawal requests.
$response = Api::Clients()->UpdateClientAffiliate([
'id' => 42,
'block_partner' => true,
'block_reason' => 'Fake referrals',
]);
```
#### Running a Fraud Check
post/api/v1/admin/clients/{id}/affiliate/fraud-check
`Clients/CheckClientAffiliateFraud` admin
Scans the partner's referrals and returns the suspicious patterns.
Body —
——No body is needed. The scan always covers the partner's whole referral history and cannot be narrowed.
Response fields data — 3
flaggedboolWhether the partner was flagged.
self_referralsintHow many referrals the partner made to themselves.
shared_ip_referralsarrayReferrals coming from the same IP as the partner.
Errors 3
not_found404No such client.
not_affiliate422The client is not an affiliate.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/affiliate/fraud-check' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/affiliate/fraud-check', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/affiliate/fraud-check');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CheckClientAffiliateFraud(['id' => 42]);
// The scan only reports; blocking is your decision and your call.
if ($response['data']['flagged'] ?? false) {
$selfReferrals = $response['data']['self_referrals'];
}
```
#### Listing Withdrawal Requests
get/api/v1/admin/clients/{id}/affiliate/withdrawals
`Clients/GetClientAffiliateWithdrawals` admin
Returns the requests the partner opened to withdraw their earnings.
Response fields data[] — 6
idintId of the withdrawal request.
amountfloatThe amount asked for.
gatewaystringThe method the payment goes out through.
statusstring`awaiting`, `process`, `completed`, `rejected` or `cancelled`.
status_msgstringA note on the status.
created_atdatetimeWhen the request was opened.
Errors 3
not_found404No such client.
not_affiliate422The client is not an affiliate.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/affiliate/withdrawals' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/affiliate/withdrawals', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/affiliate/withdrawals');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientAffiliateWithdrawals(['id' => 42]);
```
#### Updating a Withdrawal Request
patch/api/v1/admin/clients/{id}/affiliate/withdrawals/{wid}
`Clients/UpdateClientAffiliateWithdrawal` admin a receipt can be attached
Changes the request status. If you made the payment, the receipt goes in the same request.
Body 4
statusstringrequiredThe new status. Older names are accepted: `pending` → `awaiting`, `inprocess` → `process`, `paid` → `completed`.
status_msgstringA message for the partner.
receiptstring | objectThe payment receipt. Accepted only on the move to `completed`. A base64 data URI, `{filename, content}` or `{url}`. Allowed: images and PDF.
remove_receiptboolRemoves the receipt already attached.
Response fields data
dataobjectThe request as it now stands. Same shape as an item in the request list.
Errors 4
not_found404No such client or withdrawal request.
status_required422`status` was empty.
file_invalid422The receipt could not be read or stored.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/affiliate/withdrawals/5' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"completed","receipt":{"url":"https://example.com/receipt.pdf"}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/affiliate/withdrawals/5', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
status: 'completed',
receipt: { url: 'https://example.com/receipt.pdf' },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/affiliate/withdrawals/5');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'status' => 'completed',
'receipt' => ['url' => 'https://example.com/receipt.pdf'],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UpdateClientAffiliateWithdrawal([
'id' => 42,
'wid' => 5,
'status' => 'completed',
'receipt' => ['url' => 'https://example.com/receipt.pdf'],
]);
```
#### Listing Canned Texts
get/api/v1/admin/clients/affiliate/templates
`Clients/GetAffiliateTemplates` admin
Returns the canned texts used in affiliate work: deactivation reasons, withdrawal notes, block reasons.
Response fields data — 3
deactivate_reasonsstring[]Reasons for closing a partnership.
withdrawal_notesstring[]Notes put on a withdrawal request.
block_reasonsstring[]Reasons for blocking.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/affiliate/templates' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/affiliate/templates', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/affiliate/templates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetAffiliateTemplates();
```
#### Adding a Canned Text
post/api/v1/admin/clients/affiliate/templates
`Clients/AddAffiliateTemplate` admin
Adds a text to the type you choose.
Body 2
typestringrequiredMetnin türü: `deactivate_reasons`, `withdrawal_notes` or `block_reasons`.
valuestringrequiredThe text to add.
Response fields data — 2
typestringThe type the text went into.
itemsstring[]That type's list as it now stands.
Errors 3
type_invalid422The type is not one of the three values.
value_required422`value` was empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/affiliate/templates' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"block_reasons","value":"Fake referrals detected"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/affiliate/templates', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ type: 'block_reasons', value: 'Fake referrals detected' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/affiliate/templates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'type' => 'block_reasons',
'value' => 'Fake referrals detected',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->AddAffiliateTemplate([
'type' => 'block_reasons',
'value' => 'Fake referrals detected',
]);
```
#### Deleting a Canned Text
delete/api/v1/admin/clients/affiliate/templates
`Clients/DeleteAffiliateTemplate` admin deleted by text
Removes a text from the list. You send the text itself, not an id.
Body 2
typestringrequiredMetnin türü: `deactivate_reasons`, `withdrawal_notes` or `block_reasons`.
valuestringrequiredThe text to remove. It has to match the stored one exactly.
Response fields data — 2
typestringThe type the text came out of.
itemsstring[]That type's list as it now stands.
Errors 3
type_invalid422The type is not one of the three values.
value_required422`value` was empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/affiliate/templates' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"block_reasons","value":"Fake referrals detected"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/affiliate/templates', {
method: 'DELETE',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ type: 'block_reasons', value: 'Fake referrals detected' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/affiliate/templates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'type' => 'block_reasons',
'value' => 'Fake referrals detected',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteAffiliateTemplate([
'type' => 'block_reasons',
'value' => 'Fake referrals detected',
]);
```
### Pitfalls
> **Values are trimmed, not refused**
>
> The commission rate is **clamped** to 0-100, a negative balance is pulled up to zero, and an unrecognised commission period becomes empty. None of these raise an error; a wrong value is quietly stored as a corrected one. Read back after writing.
> **Blocking cancels waiting payouts**
>
> `block_partner` does not only stop the partner; it also cancels the waiting withdrawal requests. Look at the request list before blocking a partner who is about to be paid.
> **The fraud scan makes no decision**
>
> The scan only reports: how many self-referrals there are and which records came from the same IP. Blocking the partner is a separate request and the decision is yours.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Blacklist and Duplicates](https://dev.wisecp.com/en/blacklist-and-duplicates)
## Account State and Bulk Actions
https://dev.wisecp.com/en/account-state-and-bulk-actions
The six endpoints that block an account, suspend or cancel its services in bulk, and chase unpaid invoices.
### Overview
These endpoints change the state of an account and of the services attached to it. That covers blocking, bulk suspension, bulk cancellation and invoice reminders.
Blocking comes in two shapes. For a single client the `block` endpoint also stores the reason; for a list, `bulk` does the same job without one. The panel walks bulk service actions one at a time to drive its progress bar. The API does the whole set in **one call**.
### Reference
#### Blocking an Account
put/api/v1/admin/clients/{id}/block
`Clients/SetClientBlock` admin sends a notification
Blocks the account or lifts the block. The client is notified.
Body 2
blockedboolrequired`true` blocks, `false` lifts the block.
reasonstringWhy it was blocked. Stored only while blocking.
Response fields data — 1
blockedboolThe block state afterwards.
Errors 3
not_found404No such client.
blocked_by_gate422The `gate:user.block` hook vetoed the operation.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/block' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"blocked":true,"reason":"Payment dispute"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/block', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ blocked: true, reason: 'Payment dispute' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/block');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'blocked' => true,
'reason' => 'Payment dispute',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SetClientBlock([
'id' => 42,
'blocked' => true,
'reason' => 'Payment dispute',
]);
// If a hook vetoes, the call returns an error and nothing is blocked.
if (isset($response['error'])) {
$code = $response['error']['code'];
}
```
#### Applying a Bulk Action
post/api/v1/admin/clients/bulk
`Clients/BulkClientActions` admin many clients
Applies the same action to a list of clients. Only member accounts are processed; admins are skipped.
Body 2
actionstringrequiredThe action to apply. `verify` marks e-mail and phone as verified, `reactivate` puts the account back to active, `block` blocks it.
idsint[]requiredThe client ids.
Response fields data — 2
actionstringThe action that was applied.
processedint[]The ids that were actually processed. Skipped admin accounts are not here, so compare against the list you sent.
Errors 3
action_invalid422The action is not one of the three values.
ids_required422`ids` was empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/bulk' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"verify","ids":[80,81]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/bulk', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ action: 'verify', ids: [80, 81] }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/bulk');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'action' => 'verify',
'ids' => [80, 81],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$sent = [80, 81, 3];
$response = Api::Clients()->BulkClientActions([
'action' => 'verify',
'ids' => $sent,
]);
// Compare the lists to see what was skipped (admin accounts are not processed).
$skipped = array_diff($sent, $response['data']['processed'] ?? []);
```
Response 200 422
```json
{
"data": {
"action": "verify",
"processed": [80, 81]
}
}
```
```json
{
"error": {
"code": "action_invalid",
"message": "action must be verify/reactivate/block."
}
}
```
#### Suspending Every Service
post/api/v1/admin/clients/{id}/services/suspend
`Clients/SuspendClientServices` admin no body
Suspends every active service the client has. The reason is written as `Account bulk suspended`.
Body —
——No body is needed. The client comes from the path and the set cannot be narrowed: every active service is taken.
Response fields data — 3
suspendedintHow many services were suspended.
idsint[]Ids of the suspended services.
failedobject[]The services that failed. Each element carries `{id, error}`. An empty array means all of them went through.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/services/suspend' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/services/suspend', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/services/suspend');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SuspendClientServices(['id' => 42]);
// Partial success is possible: some go through, others come back in 'failed'.
foreach ($response['data']['failed'] ?? [] as $fail) {
$serviceId = $fail['id'];
$reason = $fail['error'];
}
```
#### Lifting the Bulk Suspension
post/api/v1/admin/clients/{id}/services/unsuspend
`Clients/UnsuspendClientServices` admin bulk suspensions only
Puts the bulk-suspended services back. It does not touch services suspended for another reason.
Body —
——No body is needed. The client comes from the path and the set is fixed: the services carrying the bulk-suspension reason.
Response fields data — 3
unsuspendedintHow many services were put back.
idsint[]Ids of the services affected.
failedobject[]The services that failed. Each element carries `{id, error}`. An empty array means all of them went through.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/services/unsuspend' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/services/unsuspend', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/services/unsuspend');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UnsuspendClientServices(['id' => 42]);
```
#### Cancelling Every Service
post/api/v1/admin/clients/{id}/services/cancel
`Clients/CancelClientServices` admin cannot be undone
Cancels every service the client has that is not already cancelled or finished.
Body —
——No body is needed. The client comes from the path; there is no field to pick single services with.
Response fields data — 3
cancelledintHow many services were cancelled.
idsint[]Ids of the cancelled services.
failedobject[]The services that failed. Each element carries `{id, error}`. An empty array means all of them went through.
Errors 3
not_found404No such client.
blocked_by_gate422The `gate:user.services_bulk_cancel` hook vetoed the operation.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/services/cancel' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/services/cancel', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/services/cancel');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CancelClientServices(['id' => 42]);
```
#### Reminding About Unpaid Invoices
post/api/v1/admin/clients/{id}/remind-invoices
`Clients/RemindClientInvoices` admin one notice per invoice
Sends a reminder notice for every unpaid invoice the client has.
Body —
——No body is needed. The client comes from the path; every unpaid invoice gets a notice, and single ones cannot be chosen.
Response fields data — 1
remindedintHow many invoices got a reminder.
Errors 3
not_found404No such client.
no_unpaid_invoices422The client has no unpaid invoices. You get an error, not an empty response.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/remind-invoices' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/remind-invoices', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/remind-invoices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->RemindClientInvoices(['id' => 42]);
// No unpaid invoices is an error here, not an empty result.
if (($response['error']['code'] ?? '') === 'no_unpaid_invoices') {
return;
}
```
### Pitfalls
> **Partial success is quiet**
>
> The bulk service endpoints can return `200` while some services still failed; those come back in the `failed` array as `{id, error}`. A client that only reads the status code will miss it.
> **Unsuspending is selective**
>
> The unsuspend endpoint only reopens services that were stopped by the **bulk suspension**. A service suspended for overdue payment or by hand stays where it is, which stops one call from silently restarting it.
> **Bulk actions skip admin accounts**
>
> An account in your list that is not a member gets skipped without a word. It does not appear in `processed`, so compare the list you sent with the one you get back.
> **The panel asks for a password, the API for a scope**
>
> Bulk cancellation asks for the admin password in the panel. The API has no such second step: the key's scope is enough. Hand out a key carrying this scope knowing exactly who holds it.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Blacklist and Duplicates](https://dev.wisecp.com/en/blacklist-and-duplicates)
## Client Configuration
https://dev.wisecp.com/en/client-configuration
The six endpoints that read and save client groups, badge thresholds and trust score tiers.
### Overview
These six endpoints read and write the installation-wide client configuration: groups, badge thresholds and trust score tiers. None of them looks at an individual client.
The trust score is worked out on four axes: service count, revenue, account age and support tickets. Each axis is a list of tiers, and a client scores whatever the tier they fall into is worth.
### Reference
#### Listing the Groups
get/api/v1/admin/clients/groups
`Clients/GetClientGroups` admin
Returns every client group in the installation.
Response fields data[] — 11
idintId of an existing group. Leave it out or send `0` for a new one.
namestringrequiredThe group name. If it is empty the group is quietly skipped.
descriptionstringA description.
colorstringBadge colour. Defaults to `#095174`.
iconstringIcon name.
discount_ratenumberThe discount rate applied to the group.
discount_productsstringProduct groups the discount covers. Comma-separated ids.
combine_discountboolLets the discount stack with other discounts.
protectionboolPuts the group under protection.
priorityintPriority order.
separate_invoicesboolIssues separate invoices for the clients in the group.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/groups' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/groups', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/groups');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientGroups();
```
#### Saving the Groups
put/api/v1/admin/clients/groups
`Clients/SaveClientGroups` admin the whole list
Saves the group list as it stands. The list you send becomes the truth: a group missing from it is deleted.
Body 1
groupsobject[]required 11 fieldsThe complete set of groups.
idintId of an existing group. Leave it out or send `0` for a new one.
namestringrequiredThe group name. If it is empty the group is quietly skipped.
descriptionstringA description.
colorstringBadge colour. Defaults to `#095174`.
iconstringIcon name.
discount_ratenumberThe discount rate applied to the group.
discount_productsstringProduct groups the discount covers. Comma-separated ids.
combine_discountboolLets the discount stack with other discounts.
protectionboolPuts the group under protection.
priorityintPriority order.
separate_invoicesboolIssues separate invoices for the clients in the group.
Response fields data[] — 11
dataobject[]The group list as it now stands. Same shape as the listing endpoint.
Errors 2
groups_invalid422`groups` is not an array.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/groups' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"groups":[{"id":5,"name":"VIP","discount_rate":10,"discount_products":"1,2","priority":1}]}'
```
```javascript
// Read the list first, change it, then send all of it back.
const current = await (await fetch('https://panel.example.com/api/v1/admin/clients/groups', {
headers: { Authorization: `Bearer ${apiKey}` },
})).json();
const groups = current.data.map((g) =>
g.id === 5 ? { ...g, discount_rate: 15 } : g);
const res = await fetch('https://panel.example.com/api/v1/admin/clients/groups', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ groups }),
});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/groups');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'groups' => [
[
'id' => 5,
'name' => 'VIP',
'discount_rate' => 10,
'priority' => 1,
],
],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Even to change one group, the WHOLE list goes back.
$groups = Api::Clients()->GetClientGroups()['data'];
foreach ($groups as &$group)
if ((int) $group['id'] === 5) $group['discount_rate'] = 15;
unset($group);
$response = Api::Clients()->SaveClientGroups(['groups' => $groups]);
```
#### Reading the Badge Thresholds
get/api/v1/admin/clients/badge-settings
`Clients/GetBadgeSettings` admin
Returns the thresholds at which client badges are earned. If none were saved, you get the defaults.
Response fields data — 5
loyal_yearsintYears needed for the loyal client badge.
rev_silverintRevenue threshold for the silver badge.
rev_goldintRevenue threshold for the gold badge.
multi_service_minintFewest services needed for the multi-service badge.
experienced_maxintUpper bound of the experienced badge.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/badge-settings' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/badge-settings', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/badge-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetBadgeSettings();
```
#### Saving the Badge Thresholds
put/api/v1/admin/clients/badge-settings
`Clients/SaveBadgeSettings` admin values get trimmed
Saves all five thresholds at once. One you leave out drops back to its default, so send the whole set. Values are pulled into a safe range rather than refused.
Body 5
loyal_yearsintLoyal client year threshold. Minimum 1.
rev_silverintSilver revenue threshold. Minimum 0.
rev_goldintGold revenue threshold. If you send it at or below silver it becomes `rev_silver + 1`.
multi_service_minintMulti-service badge minimum. Minimum 1.
experienced_maxintExperienced badge upper bound. Minimum 0.
Response fields data — 5
dataobjectThe thresholds as they now stand. Same shape as the read endpoint.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/badge-settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"loyal_years":5,"rev_silver":500,"rev_gold":1000,"multi_service_min":5,"experienced_max":15}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/badge-settings', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
loyal_years: 5,
rev_silver: 500,
rev_gold: 1000,
multi_service_min: 5,
experienced_max: 15,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/badge-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'loyal_years' => 5,
'rev_silver' => 500,
'rev_gold' => 1000,
'multi_service_min' => 5,
'experienced_max' => 15,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SaveBadgeSettings([
'rev_silver' => 500,
'rev_gold' => 400,
]);
// The response carries what was stored: rev_gold comes back as 501 here.
$saved = $response['data']['rev_gold'];
```
#### Reading the Trust Score Tiers
get/api/v1/admin/clients/trust-score-settings
`Clients/GetTrustScoreSettings` admin
Returns the tiers on all four trust score axes. If none were saved, you get the defaults.
Response fields data — 4
servicesobject[] 2 fieldsThe service count axis.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
revenueobject[] 2 fieldsThe revenue axis.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
ageobject[] 2 fieldsThe account age axis.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
ticketsobject[] 2 fieldsThe support ticket axis.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/trust-score-settings' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/trust-score-settings', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/trust-score-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetTrustScoreSettings();
```
Response 200
```json
{
"data": {
"services": [
{ "max": 5, "points": 20 },
{ "max": null, "points": 30 }
],
"revenue": [{ "max": 1000, "points": 25 }],
"age": [{ "max": 12, "points": 10 }],
"tickets": [{ "max": null, "points": 5 }]
}
}
```
#### Saving the Trust Score Tiers
put/api/v1/admin/clients/trust-score-settings
`Clients/SaveTrustScoreSettings` admin all four axes at once
Saves all four axes at once. An axis you leave out is saved empty and loses its tiers, so send every axis you want to keep.
Body 4
servicesobject[] 2 fieldsService count tiers.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
revenueobject[] 2 fieldsRevenue tiers.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
ageobject[] 2 fieldsAccount age tiers.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
ticketsobject[] 2 fieldsSupport ticket tiers.
maxint | nullrequiredThe upper bound of the tier. `null` is the last, unbounded tier.
pointsintrequiredThe points the tier is worth.
Response fields data — 4
dataobjectThe tiers as they now stand. Same shape as the read endpoint.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/trust-score-settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"services":[{"max":5,"points":20},{"max":null,"points":30}]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/trust-score-settings', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
services: [
{ max: 5, points: 20 },
{ max: null, points: 30 },
],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/trust-score-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'services' => [
['max' => 5, 'points' => 20],
['max' => null, 'points' => 30],
],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The last tier needs 'max' => null, or a client above the bound scores nothing.
$response = Api::Clients()->SaveTrustScoreSettings([
'services' => [
['max' => 5, 'points' => 20],
['max' => null, 'points' => 30],
],
]);
```
### Pitfalls
> **Saving groups replaces the whole list**
>
> The save endpoint does not merge. A group missing from the list you send is **deleted**, and the clients in it are left without one. To change a single group, read the list first, edit it, and send all of it back.
> **The gold threshold is pushed above silver**
>
> Sending the gold revenue threshold at or below silver does not raise an error; the value quietly becomes `rev_silver + 1`. Read the response to see what was stored.
> **The last tier has to be unbounded**
>
> Leave `max` as `null` on an axis's last tier. Otherwise a client above the highest bound falls into no tier and scores nothing on that axis.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Account State and Bulk Actions](https://dev.wisecp.com/en/account-state-and-bulk-actions)
## WHOIS Profiles
https://dev.wisecp.com/en/whois-profiles
The six endpoints that manage the registrant profiles a client uses on domain orders.
### Overview
A WHOIS profile is the registrant data a client reuses across domain orders. A client can hold several profiles but only **one default**.
The fields are `snake_case` and carry the same names as the domain WHOIS contact endpoints. Storage uses a different shape, but the API converts it, so that is not your concern.
### Reference
#### Listing the Profiles
get/api/v1/admin/clients/{id}/whois-profiles
`Clients/GetClientWhoisProfiles` admin default first
Returns every WHOIS profile the client has. The default one comes first.
Response fields data[] — 6
idintProfile id.
namestringProfile name.
is_defaultboolWhether it is the client's default.
contactobject 14 fieldsThe contact fields.
first_namestringThe registrant's first name.
last_namestringThe registrant's last name.
companystringCompany name.
emailstringE-mail address.
phonestringPhone number without the country code.
phone_ccstringCountry code for the phone.
faxstringFax number.
fax_ccstringCountry code for the fax.
address_line1stringFirst line of the address.
address_line2stringSecond line of the address.
citystringCity.
statestringState or province.
zipcodestringPostal code.
countrystringCountry code. The numeric code, not the two-letter one: `840`.
created_atstringWhen it was created.
updated_atstringWhen it was last changed.
Errors 2
not_found404No such client or profile.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/whois-profiles' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/whois-profiles', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/whois-profiles');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientWhoisProfiles(['id' => 42]);
// The default is first, but be ready for an empty list.
$default = $response['data'][0] ?? null;
```
Response 200
```json
{
"data": [
{
"id": 13,
"name": "Primary",
"is_default": true,
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"phone": "5550100",
"phone_cc": "1",
"address_line1": "123 Market Street",
"city": "San Francisco",
"state": "California",
"zipcode": "94105",
"country": "840"
},
"created_at": "2026-06-21 18:00:00",
"updated_at": "2026-06-21 18:05:00"
}
]
}
```
#### Creating a Profile
post/api/v1/admin/clients/{id}/whois-profiles
`Clients/CreateClientWhoisProfile` admin 201
Adds a new WHOIS profile to the client.
Body 3
namestringrequiredThe profile name.
contactobject 14 fieldsThe contact fields.
first_namestringThe registrant's first name.
last_namestringThe registrant's last name.
companystringCompany name.
emailstringE-mail address.
phonestringPhone number without the country code.
phone_ccstringCountry code for the phone.
faxstringFax number.
fax_ccstringCountry code for the fax.
address_line1stringFirst line of the address.
address_line2stringSecond line of the address.
citystringCity.
statestringState or province.
zipcodestringPostal code.
countrystringCountry code. The numeric code, not the two-letter one: `840`.
defaultboolMakes the profile the client's default.
Response fields data — 6
dataobjectThe profile created. Same shape as the detail endpoint.
Errors 4
not_found404No such client or profile.
name_required422The profile name was empty.
create_failed500The profile could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/whois-profiles' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"name": "Primary",
"default": true,
"contact": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com",
"country": "840"
}
}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/whois-profiles', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Primary',
default: true,
contact: {
first_name: 'John',
last_name: 'Doe',
email: 'john@example.com',
phone: '5550100',
phone_cc: '1',
address_line1: '123 Market Street',
city: 'San Francisco',
state: 'California',
zipcode: '94105',
country: '840',
},
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/whois-profiles');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Primary',
'default' => true,
'contact' => [
'first_name' => 'John',
'last_name' => 'Doe',
'email' => 'john@example.com',
'phone' => '5550100',
'phone_cc' => '1',
'address_line1' => '123 Market Street',
'city' => 'San Francisco',
'state' => 'California',
'zipcode' => '94105',
'country' => '840',
],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClientWhoisProfile([
'id' => 42,
'name' => 'Primary',
'default' => true,
'contact' => [
'first_name' => 'John',
'last_name' => 'Doe',
'email' => 'john@example.com',
'phone' => '5550100',
'phone_cc' => '1',
'address_line1' => '123 Market Street',
'city' => 'San Francisco',
'state' => 'California',
'zipcode' => '94105',
'country' => '840',
],
]);
$profileId = $response['data']['id'];
```
Response 201 422
```json
{
"data": {
"id": 14,
"name": "Primary",
"is_default": true,
"contact": { "first_name": "John", "last_name": "Doe", "country": "840" },
"created_at": "2026-06-21 18:00:00",
"updated_at": "2026-06-21 18:00:00"
}
}
```
```json
{
"error": {
"code": "name_required",
"message": "Profile name is required."
}
}
```
#### Profile Detail
get/api/v1/admin/clients/{id}/whois-profiles/{pid}
`Clients/GetClientWhoisProfile` admin
Returns one profile. The schema is the same as a list item.
Response fields data — 6
idintProfile id.
namestringProfile name.
is_defaultboolWhether it is the client's default.
contactobject 14 fieldsThe contact fields.
first_namestringThe registrant's first name.
last_namestringThe registrant's last name.
companystringCompany name.
emailstringE-mail address.
phonestringPhone number without the country code.
phone_ccstringCountry code for the phone.
faxstringFax number.
fax_ccstringCountry code for the fax.
address_line1stringFirst line of the address.
address_line2stringSecond line of the address.
citystringCity.
statestringState or province.
zipcodestringPostal code.
countrystringCountry code. The numeric code, not the two-letter one: `840`.
created_atstringWhen it was created.
updated_atstringWhen it was last changed.
Errors 2
not_found404No such client or profile.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientWhoisProfile(['id' => 42, 'pid' => 13]);
```
#### Updating a Profile
put/api/v1/admin/clients/{id}/whois-profiles/{pid}
`Clients/UpdateClientWhoisProfile` admin contact is written whole
Updates the profile. A top-level field you leave out stays as it was.
Body 3
namestringThe profile name. Leave it out and the current name is kept.
contactobject 14 fieldsThe contact fields. If you send it, the block is written whole, so a missing field is emptied.
first_namestringThe registrant's first name.
last_namestringThe registrant's last name.
companystringCompany name.
emailstringE-mail address.
phonestringPhone number without the country code.
phone_ccstringCountry code for the phone.
faxstringFax number.
fax_ccstringCountry code for the fax.
address_line1stringFirst line of the address.
address_line2stringSecond line of the address.
citystringCity.
statestringState or province.
zipcodestringPostal code.
countrystringCountry code. The numeric code, not the two-letter one: `840`.
defaultbool`true` makes it the default, `false` takes that away.
Response fields data — 6
dataobjectThe profile as it now stands. Same shape as the detail endpoint.
Errors 3
not_found404No such client or profile.
name_required422The profile name you sent was empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Billing Contact"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name: 'Billing Contact' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['name' => 'Billing Contact']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// To change one contact field, read the current block first.
$current = Api::Clients()->GetClientWhoisProfile(['id' => 42, 'pid' => 13])['data']['contact'];
$current['email'] = 'billing@example.com';
$response = Api::Clients()->UpdateClientWhoisProfile([
'id' => 42,
'pid' => 13,
'contact' => $current,
]);
```
#### Setting the Default
put/api/v1/admin/clients/{id}/whois-profiles/{pid}/default
`Clients/SetClientWhoisProfileDefault` admin one default only
Makes the profile the client's default. The previous default is cleared in the same operation.
Body —
——No body is needed; send an empty one. Both the client and the profile come from the path.
Response fields data — 2
idintId of the profile that became the default.
defaultboolAlways comes back as `true`.
Errors 2
not_found404No such client or profile.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13/default' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13/default', {
method: 'PUT',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13/default');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SetClientWhoisProfileDefault(['id' => 42, 'pid' => 13]);
```
#### Deleting a Profile
delete/api/v1/admin/clients/{id}/whois-profiles/{pid}
`Clients/DeleteClientWhoisProfile` admin
Deletes the profile. Contact data already registered on domains is not affected.
Response fields data — 2
deletedboolWhether the delete succeeded.
idintId of the deleted profile.
Errors 2
not_found404No such client or profile.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/whois-profiles/13');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientWhoisProfile(['id' => 42, 'pid' => 13]);
```
### Pitfalls
> **The contact block is written whole**
>
> Sending `contact` on an update replaces the entire block, and the fields you left out are **emptied**. To change one field, read the current block, edit it, and send all of it back. This differs from the top-level fields: leave out `name` and it is kept.
> **The country goes in as a numeric code**
>
> The `country` field wants the numeric code, not the two-letter one: `840` for the United States. Sending the abbreviation leaves the profile without a country and the domain registration can fail at the registrar.
> **Moving the default is quiet**
>
> Making a profile the default clears the client's previous default in the same operation. There is no separate confirmation or warning, so read the list back to check the outcome.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Client Addresses](https://dev.wisecp.com/en/client-addresses)
## Sending Notifications
https://dev.wisecp.com/en/sending-notifications
The five endpoints that send a client a template, an e-mail or an SMS, and read the result back.
### Overview
These endpoints send a message to a client and read back what was sent. There are three ways to send: a stored template, a free e-mail and a free SMS.
Every send is **synchronous**. The response comes after the dispatch attempt finishes; nothing is queued. A slow provider slows your request down with it.
### Reference
#### Previewing the Recipients
get/api/v1/admin/clients/{id}/notifications/recipients
`Clients/GetClientNotificationRecipients` admin sends nothing
Returns who a template would reach, without sending anything.
Query parameters 2
templatestringThe template id, in `group/name` form.
channelstring`email` or `sms`. Give it and you get only that channel's recipients.
Response fields data — 2
mailobject[]The e-mail recipients. Each element carries `email` and `name`.
smsobject[]The SMS recipients. An empty array when the client has no phone.
Errors 3
not_found404No such client.
template_invalid422`template` is not in `group/name` form.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients/42/notifications/recipients' \
-H "Authorization: Bearer $API_KEY" \
-d template=user/welcome
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients/42/notifications/recipients');
url.searchParams.set('template', 'user/welcome');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients/42/notifications/recipients?' . http_build_query(['template' => 'user/welcome']);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Check for recipients first: a template with none comes back as a 500.
$preview = Api::Clients()->GetClientNotificationRecipients([
'id' => 42,
'template' => 'user/welcome',
], ['channel' => 'email']);
if (!($preview['data']['mail'] ?? [])) {
return;
}
```
Response 200
```json
{
"data": {
"mail": [
{ "email": "john@example.com", "name": "John Doe" }
],
"sms": []
}
}
```
#### Sending a Template
post/api/v1/admin/clients/{id}/notifications/template
`Clients/SendClientTemplate` admin synchronous
Sends a stored notification template to the client.
Body 2
templatestringrequiredThe template id, in `group/name` form. Both halves have to be filled: `user/welcome`.
channelstring`email` or `sms`. Defaults to `email`.
Response fields data — 3
sentboolAlways `true`. A failure comes back as an error, not as a value in this field.
channelstringThe channel that was used.
templatestringId of the template that was sent.
Errors 4
not_found404No such client.
template_invalid422`template` is not in `group/name` form.
send_failed500The dispatch failed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/notifications/template' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"template":"user/welcome","channel":"email"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/notifications/template', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ template: 'user/welcome', channel: 'email' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/notifications/template');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'template' => 'user/welcome',
'channel' => 'email',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SendClientTemplate([
'id' => 42,
'template' => 'user/welcome',
'channel' => 'email',
]);
```
#### Sending a Custom E-mail
post/api/v1/admin/clients/{id}/notifications/email
`Clients/SendClientEmail` admin synchronous
Sends an e-mail with a free subject and body, without going through a template.
Body 3
subjectstringrequiredThe subject line.
messagestringrequiredThe body.
copy_to_adminboolCopies the sending admin. Off by default.
Response fields data — 1
sentboolAlways `true`.
Errors 5
not_found404No such client.
subject_required422`subject` was empty.
message_required422`message` was empty.
send_failed500The dispatch failed **or there was no valid recipient**.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/notifications/email' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"subject":"An update about your account","message":"Hello, your request has been processed.","copy_to_admin":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/notifications/email', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
subject: 'An update about your account',
message: 'Hello, your request has been processed.',
copy_to_admin: true,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/notifications/email');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'subject' => 'An update about your account',
'message' => 'Hello, your request has been processed.',
'copy_to_admin' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SendClientEmail([
'id' => 42,
'subject' => 'An update about your account',
'message' => 'Hello, your request has been processed.',
]);
// 'send_failed' covers both a failed dispatch and no recipient at all.
$failed = ($response['error']['code'] ?? '') === 'send_failed';
```
#### Sending a Custom SMS
post/api/v1/admin/clients/{id}/notifications/sms
`Clients/SendClientSms` admin synchronous
Sends the client an SMS with free content.
Body 1
messagestringrequiredThe message body.
Response fields data — 1
sentboolAlways `true`.
Errors 4
not_found404No such client.
message_required422`message` was empty.
send_failed500The dispatch failed or there was no valid recipient.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/notifications/sms' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"message":"Hello, your request has been processed."}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/notifications/sms', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ message: 'Hello, your request has been processed.' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/notifications/sms');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['message' => 'Hello, your request has been processed.']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SendClientSms([
'id' => 42,
'message' => 'Hello, your request has been processed.',
]);
```
#### Reading a Sent Message
get/api/v1/admin/clients/messages/preview
`Clients/GetMessagePreview` admin decrypted
Returns the content of an e-mail or SMS that was sent earlier.
Query parameters 2
typestringrequired`email` ya da `sms`.
idintrequiredThe log record id. Not the client id, the record's own id.
Response fields data — 2
typestringThe record type.
contentstringThe decrypted message content.
Errors 2
invalid_request422`type` or `id` is missing or invalid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients/messages/preview' \
-H "Authorization: Bearer $API_KEY" \
-d type=email \
-d id=901
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients/messages/preview');
url.searchParams.set('type', 'email');
url.searchParams.set('id', '901');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients/messages/preview?' . http_build_query(['type' => 'email', 'id' => 901]);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetMessagePreview([], [
'type' => 'email',
'id' => 901,
]);
$content = $response['data']['content'];
```
### Pitfalls
> **The sent field is always true**
>
> The `sent` field in the response is a constant, not an outcome. A failure arrives as an error body, not as this field turning `false`. Branch on the error code, not on the field.
> **A send with no recipient returns a 500**
>
> If the client has no e-mail or phone the error is `send_failed`. That is not a server fault, it is the absence of a recipient. To tell them apart, call the preview endpoint first and skip the send when the list comes back empty.
> **The request waits for the dispatch**
>
> Nothing is queued. If you are writing a batch job you pay the provider's response time for every client, so set your timeout accordingly.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Account State and Bulk Actions](https://dev.wisecp.com/en/account-state-and-bulk-actions)
## Sub-users
https://dev.wisecp.com/en/sub-users
The five endpoints that manage the limited-permission accounts reaching a client's panel.
### Overview
A sub-user is a second person who reaches a client's panel with limited permissions: the accountant sees only invoices, the technical team only services.
The permission set is **fixed** and holds ten values. The owner's own profile, billing contacts and e-mail history cannot be handed over; those stay with the account itself.
### Reference
#### Listing the Sub-users
get/api/v1/admin/clients/{id}/subusers
`Clients/GetClientSubusers` admin
Returns every sub-user the client has.
Response fields data[] — 12
idintSub-user id.
emailstringE-mail address.
labelstring | nullA label. For a department or role name.
statusstring`pending` is awaiting the invite, `active` is live, `inactive` is switched off.
permissionsarray 10 permissionsThe permissions granted.
view_servicespermissionSees the services.
view_passwordspermissionSees service passwords.
allow_ssopermissionSigns in to a service panel in one click.
view_domainspermissionSees the domains.
manage_domainspermissionManages the domains.
view_invoicespermissionSees the invoices.
view_ticketspermissionSees the support tickets.
view_affiliatepermissionSees the affiliate page.
view_resellerpermissionSees the reseller page.
new_orderspermissionPlaces new orders.
email_notificationsintE-mail notification preference. A bitmask.
sms_notificationsintSMS notification preference. A bitmask.
linked_user_idintId of the real client account it is linked to. `0` when there is none.
linked_user_namestring | nullName of the linked account.
invited_atstring | nullWhen the invite went out.
accepted_atstring | nullWhen the invite was accepted.
created_atstring | nullWhen the record was created.
Errors 2
not_found404No such client or sub-user.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/subusers' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/subusers', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/subusers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientSubusers(['id' => 42]);
```
Response 200
```json
{
"data": [
{
"id": 4,
"email": "accounting@example.com",
"label": "Accounting",
"status": "active",
"permissions": ["view_invoices", "view_services"],
"email_notifications": 0,
"sms_notifications": 0,
"linked_user_id": 31,
"linked_user_name": "John Doe",
"invited_at": "2026-06-01 10:00:00",
"accepted_at": "2026-06-02 09:12:00",
"created_at": "2026-06-01 10:00:00"
}
]
}
```
#### Adding a Sub-user
post/api/v1/admin/clients/{id}/subusers
`Clients/CreateClientSubuser` admin 201
Adds a sub-user to the client. The record starts out `pending`.
Body 6
emailstringrequiredE-mail address. It has to differ from the owner's and not be in use already.
labelstringA label.
permissionsarray 10 permissionsThe permissions to grant. An unrecognised key is dropped without a word.
view_servicespermissionSees the services.
view_passwordspermissionSees service passwords.
allow_ssopermissionSigns in to a service panel in one click.
view_domainspermissionSees the domains.
manage_domainspermissionManages the domains.
view_invoicespermissionSees the invoices.
view_ticketspermissionSees the support tickets.
view_affiliatepermissionSees the affiliate page.
view_resellerpermissionSees the reseller page.
new_orderspermissionPlaces new orders.
email_notificationsintE-mail notification preference. Defaults to 0.
sms_notificationsintSMS notification preference. Defaults to 0.
send_inviteboolSends the invite e-mail. On by default.
Response fields 201 — data
dataobjectThe sub-user created. Same shape as the listing endpoint.
Errors 6
not_found404No such client or sub-user.
email_invalid422The e-mail is not valid.
email_is_owner422The e-mail is the owner's own.
email_exists422A sub-user with this e-mail already exists.
subuser_add_failed500The insert failed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/subusers' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"email":"accounting@example.com","label":"Accounting","permissions":["view_invoices","view_services"]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/subusers', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
email: 'accounting@example.com',
label: 'Accounting',
permissions: ['view_invoices', 'view_services'],
send_invite: true,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/subusers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'email' => 'accounting@example.com',
'label' => 'Accounting',
'permissions' => ['view_invoices', 'view_services'],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->CreateClientSubuser([
'id' => 42,
'email' => 'accounting@example.com',
'permissions' => ['view_invoices', 'view_services'],
]);
// Read the granted permissions back: an unrecognised key is dropped silently.
$granted = $response['data']['permissions'];
```
#### Updating a Sub-user
patch/api/v1/admin/clients/{id}/subusers/{subuser_id}
`Clients/UpdateClientSubuser` admin can link an account
Updates the fields you send and leaves the rest alone.
Body 5
labelstringThe label.
statusstringThe new status. An unrecognised value keeps the current one.
permissionsarray 10 permissionsThe permission list. If you send it, the list is written whole.
view_servicespermissionSees the services.
view_passwordspermissionSees service passwords.
allow_ssopermissionSigns in to a service panel in one click.
view_domainspermissionSees the domains.
manage_domainspermissionManages the domains.
view_invoicespermissionSees the invoices.
view_ticketspermissionSees the support tickets.
view_affiliatepermissionSees the affiliate page.
view_resellerpermissionSees the reseller page.
new_orderspermissionPlaces new orders.
email_notificationsintE-mail notification preference.
sms_notificationsintSMS notification preference.
Response fields data
dataobjectThe sub-user as it now stands. Same shape as the listing endpoint.
Errors 2
not_found404No such client or sub-user.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/subusers/5' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"active"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/subusers/5', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: 'active' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/subusers/5');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['status' => 'active']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->UpdateClientSubuser([
'id' => 42,
'subuser_id' => 5,
'status' => 'active',
]);
// Going active for the first time links a real account when the e-mail matches.
$linkedTo = $response['data']['linked_user_id'];
```
#### Resending the Invite
post/api/v1/admin/clients/{id}/subusers/{subuser_id}/resend-invite
`Clients/ResendClientSubuserInvite` admin pending only
Sends the invite again to a sub-user still waiting for one.
Body —
——No body is needed, send an empty one. The invite goes to the address already stored on the record and cannot be redirected here.
Response fields data — 2
resentboolWhether the invite went out again.
idintSub-user id.
Errors 3
not_found404No such client or sub-user.
not_pending422The sub-user is not awaiting an invite. A live or switched-off record cannot be invited.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/clients/42/subusers/5/resend-invite' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/subusers/5/resend-invite', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/subusers/5/resend-invite');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->ResendClientSubuserInvite([
'id' => 42,
'subuser_id' => 5,
]);
```
#### Deleting a Sub-user
delete/api/v1/admin/clients/{id}/subusers/{subuser_id}
`Clients/DeleteClientSubuser` admin
Deletes the sub-user. The real client account it was linked to is not affected.
Response fields data — 2
deletedboolWhether the delete succeeded.
idintId of the deleted sub-user.
Errors 2
not_found404No such client or sub-user.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/clients/42/subusers/5' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/subusers/5', {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/subusers/5');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->DeleteClientSubuser([
'id' => 42,
'subuser_id' => 5,
]);
```
### Pitfalls
> **An unrecognised permission is dropped silently**
>
> The permission list is a closed set. Send a key that is not in it and you get no error; the key is thrown away and the record is stored with fewer permissions than you meant. Read the `permissions` field back from the write to see what was granted.
> **Going active can link an account**
>
> The first time a sub-user is set to `active`, a matching e-mail on an existing client account **links that account**. That means someone can sign in as themselves and step into another client's panel, so know whose e-mail it is before changing status.
> **The invite only goes to one still waiting**
>
> The resend endpoint only works on a record that is still `pending`. To invite a live sub-user you have to move the status back first.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Client Security Endpoints](https://dev.wisecp.com/en/client-security-endpoints)
## Reseller
https://dev.wisecp.com/en/reseller-endpoints
The five endpoints that manage a client's reseller status and the programme's installation-wide settings.
### Overview
A reseller partnership is a client buying from you at a discount and selling on to their own customers. These endpoints run two separate layers that should not be confused.
The first three look at **one client**: their reseller status, credit threshold and discount tiers. The last two run **the programme itself**: how applications are approved, whether verification is required, whether resellers get API access. Whether the path carries a client id tells you which layer you are on.
### Reference
#### Reading the Reseller Status
get/api/v1/admin/clients/{id}/reseller
`Clients/GetClientReseller` admin two shapes
Returns the client's reseller status and the settings that belong to them.
Response fields data — 7
is_resellerboolWhether the partnership is live. With no reseller record at all, this is the only field in the response.
statusstring`active` or `inactive`.
activation_timedatetime | nullWhen it first went live.
min_creditobject 2 fieldsThe credit needed to buy.
amountfloatThe amount.
currency_idintCurrency id.
min_discountobject 2 fieldsThe balance needed for the discount to apply.
amountfloatThe amount.
currency_idintCurrency id.
only_credit_paymentboolWhether paying by credit is the only option.
discountsobject 3 fieldsA map from product group id to discount tiers.
fromintLower bound of the tier.
tointUpper bound of the tier.
ratefloatThe discount rate for the tier.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/reseller' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/reseller', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
// With no reseller record the response holds a single field.
if (!body.data.is_reseller) return;
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/reseller');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientReseller(['id' => 42]);
// The other fields only arrive when a record exists - read them null-safe.
$minCredit = $response['data']['min_credit']['amount'] ?? 0;
```
Response 200 200
```json
{
"data": {
"is_reseller": true,
"status": "active",
"activation_time": "2026-02-01 12:00:00",
"min_credit": { "amount": 100.00, "currency_id": 840 },
"min_discount": { "amount": 50.00, "currency_id": 840 },
"only_credit_payment": false,
"discounts": {
"5": [{ "from": 1, "to": 10, "rate": 15.0 }]
}
}
}
```
```json
{
"data": {
"is_reseller": false
}
}
```
#### Saving the Reseller Settings
patch/api/v1/admin/clients/{id}/reseller
`Clients/UpdateClientReseller` admin notifies on first activation
Saves the reseller settings that belong to the client and switches the partnership on or off.
Body 5
activeboolSwitches the partnership on or off.
min_creditobject 2 fieldsThe minimum credit requirement. Only meaningful while the partnership is on.
amountfloatThe amount.
currency_idintCurrency id.
min_discountobject 2 fieldsThe minimum balance for the discount. Only meaningful while the partnership is on.
amountfloatThe amount.
currency_idintCurrency id.
only_credit_paymentboolLimits payment to credit.
discountsobject 3 fieldsA map from product group id to discount tiers.
fromintLower bound of the tier.
tointUpper bound of the tier.
ratefloatThe discount rate for the tier.
Response fields data
dataobjectThe reseller record after the save. Same shape as the read endpoint.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/clients/42/reseller' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"active":true,"min_credit":{"amount":100,"currency_id":840},"only_credit_payment":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/reseller', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
active: true,
min_credit: { amount: 100, currency_id: 840 },
only_credit_payment: true,
discounts: {
5: [{ from: 1, to: 10, rate: 15 }],
},
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/reseller');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'active' => true,
'min_credit' => ['amount' => 100, 'currency_id' => 840],
'only_credit_payment' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// While the partnership is on, a setting you omit REMOVES that limit - read the current state first.
$current = Api::Clients()->GetClientReseller(['id' => 42])['data'];
$response = Api::Clients()->UpdateClientReseller([
'id' => 42,
'active' => true,
'min_credit' => $current['min_credit'],
'min_discount' => $current['min_discount'],
'only_credit_payment' => true,
'discounts' => $current['discounts'],
]);
```
#### Changing the Reseller Status
put/api/v1/admin/clients/{id}/reseller/status
`Clients/SetClientResellerStatus` admin leaves settings alone
Switches an existing reseller record on or off. The settings stay as they are.
Body 1
actionstringrequired`activate` or `terminate`.
Response fields data — 2
statusstringThe status afterwards.
is_resellerboolWhether the partnership is live.
Errors 3
not_found404No such client.
action_invalid422`action` is neither of the two values.
not_reseller422The client has no reseller record. Create one with the settings endpoint first.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/42/reseller/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"activate"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/reseller/status', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ action: 'activate' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/reseller/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['action' => 'activate']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SetClientResellerStatus([
'id' => 42,
'action' => 'activate',
]);
```
#### Reading the Programme Settings
get/api/v1/admin/clients/reseller/config
`Clients/GetResellerConfig` admin installation-wide
Returns the installation-wide settings of the reseller programme. It looks at no single client.
Response fields data — 10
enabledboolWhether the programme is on.
activationstringHow applications are approved. The stored value is `manuel` or `auto`.
allow_non_membersboolWhether non-members can see the reseller storefront.
api_accessboolWhether resellers get API access.
payment_restrictionboolWhether payment is limited to credit.
verificationboolWhether applications must be verified.
verification_methodsstring[]The verification methods required.
min_creditobject 2 fieldsThe minimum credit amount.
amountfloatThe amount.
currency_idintCurrency id.
credit_thresholdobject 2 fieldsThe credit threshold.
amountfloatThe amount.
currency_idintCurrency id.
discount_ratesobject 3 fieldsA map from product group id to discount tiers.
fromintLower bound of the tier.
tointUpper bound of the tier.
ratefloatThe discount rate for the tier.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/reseller/config' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/reseller/config', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/reseller/config');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetResellerConfig();
```
#### Saving the Programme Settings
put/api/v1/admin/clients/reseller/config
`Clients/SaveResellerConfig` admin installation-wide
Saves the installation-wide settings of the reseller programme.
Body 10
enabledboolTurns the programme on or off.
activationstring`manual`, `automatic` or `auto`. An unrecognised value falls back to manual approval.
allow_non_membersboolOpens the storefront to non-members.
api_accessboolGives resellers API access.
payment_restrictionboolLimits payment to credit.
verificationboolMakes verification mandatory on application.
verification_methodsstring[]The verification methods to require.
min_creditobject 2 fieldsThe minimum credit amount.
amountfloatThe amount.
currency_idintCurrency id.
credit_thresholdobject 2 fieldsThe credit threshold.
amountfloatThe amount.
currency_idintCurrency id.
discount_ratesobject 3 fieldsA map from product group id to discount tiers.
fromintLower bound of the tier.
tointUpper bound of the tier.
ratefloatThe discount rate for the tier.
Response fields data
dataobjectThe programme settings after the save. Same shape as the read endpoint.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/clients/reseller/config' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true,"activation":"manual","api_access":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/reseller/config', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
enabled: true,
activation: 'manual',
api_access: true,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/reseller/config');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'enabled' => true,
'activation' => 'manual',
'api_access' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SaveResellerConfig([
'enabled' => true,
'activation' => 'manual',
'api_access' => true,
]);
```
### Pitfalls
> **A setting you omit removes the limit**
>
> Saving settings while the partnership is on **drops** any limit you did not send; the old value is not kept. Forgetting the credit threshold while you only meant to change the payment restriction removes that threshold. Read the current settings, edit them, and send all of it back.
> **The response shape depends on the record**
>
> With no reseller record the status endpoint returns only `is_reseller` and the other fields are **absent**. Read them null-safe rather than directly, or every non-reseller client will break your code.
> **The status endpoint cannot create a partnership**
>
> The quick toggle only changes an existing record; on a client without one it returns `not_reseller`. Opening a new partnership is the settings endpoint's job.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Affiliate](https://dev.wisecp.com/en/affiliate-endpoints)
## Quick Reads
https://dev.wisecp.com/en/quick-reads
The four read-only endpoints that search clients, give the counts and fill the summary card.
### Overview
These four endpoints tell you something quickly about a client and change nothing. The panel's search box, dashboard counters and summary card all read from them.
Two look across the installation (search and statistics) and two at a single client (summary and the standout note). Whether the path carries a client id tells you which one you are on.
### Reference
#### Searching for a Client
get/api/v1/admin/clients/search
`Clients/SearchClients` admin autocomplete
Searches clients by name, company or e-mail. It was written for autocomplete boxes.
Query parameters 1
qstringThe search term. The name `search` is accepted too.
Response fields data[] — 4
idintClient id.
full_namestringFirst and last name.
company_namestringCompany name.
textstringA ready-made display label with the name and company joined.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients/search' \
-H "Authorization: Bearer $API_KEY" \
-d q=acme
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients/search');
url.searchParams.set('q', 'acme');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients/search?' . http_build_query(['q' => 'acme']);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->SearchClients([], ['q' => 'acme']);
```
#### Client Statistics
get/api/v1/admin/clients/stats
`Clients/GetClientsStats` admin all clients
Returns the counts across every client in the installation. It looks at no single client.
Query parameters 1
periodstringThe period: `all_time`, `today`, `week`, `month` or `year`. Defaults to `all_time`.
Response fields data — 9
activeintHow many clients are active.
blockedintHow many clients are blocked.
newintHow many clients arrived in the period.
blacklistedintHow many clients are blacklisted.
active_servicesintHow many services are live.
unpaid_invoicesintHow many invoices are unpaid.
credit_balancefloatThe total credit balance. A raw number; the currency symbol is yours to add.
growth_ratefloatThe growth rate as a percentage.
totalintThe total client count in the period.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -G 'https://panel.example.com/api/v1/admin/clients/stats' \
-H "Authorization: Bearer $API_KEY" \
-d period=month
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/clients/stats');
url.searchParams.set('period', 'month');
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const body = await res.json();
```
```php
$url = 'https://panel.example.com/api/v1/admin/clients/stats?' . http_build_query(['period' => 'month']);
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientsStats([], ['period' => 'month']);
```
Response 200
```json
{
"data": {
"active": 120,
"blocked": 3,
"new": 18,
"blacklisted": 2,
"active_services": 340,
"unpaid_invoices": 41,
"credit_balance": 14620.12,
"growth_rate": 4.5,
"total": 145
}
}
```
#### Client Summary
get/api/v1/admin/clients/{id}/summary
`Clients/GetClientSummary` admin badges and trust score
Returns summary card data for one client: revenue, service and ticket counts, badges, trust score.
Response fields data — 13
user_idintClient id.
full_namestringFirst and last name.
company_namestringCompany name.
created_atstringWhen they joined. A raw value; formatting is yours.
total_revenuefloatWhat they have paid in total so far.
revenue_currencyintCurrency id of the amount. List: `reference/currencies`.
paid_invoicesintHow many invoices were paid.
active_servicesintHow many services are live.
inactive_servicesintHow many services are not live.
total_ticketsintHow many tickets in total.
recent_ticketsintHow many tickets recently.
badgesobject 4 fieldsWhich badges were earned.
loyalboolThe membership age threshold was passed.
revenueboolThe revenue threshold was passed.
multi_serviceboolThey hold more than one live service.
experiencedboolThe past interaction threshold was passed.
trust_scoreobject 6 fieldsThe trust score and its parts.
totalintThe total score. Between 0 and 100.
labelstring`poor`, `fair`, `good` ya da `excellent`.
servicesintPoints from the service axis.
revenueintPoints from the revenue axis.
ageintPoints from the account age axis.
ticketsintPoints from the support ticket axis.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/summary' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/summary', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/summary');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientSummary(['id' => 42]);
// The parts tell you where the score came from.
$score = $response['data']['trust_score'];
$fromServices = $score['services'];
```
Response 200
```json
{
"data": {
"user_id": 9,
"full_name": "Test Client",
"company_name": "",
"created_at": "2021-03-18 00:00:00",
"total_revenue": 36,
"revenue_currency": 4,
"paid_invoices": 1,
"active_services": 16,
"inactive_services": 16,
"total_tickets": 0,
"recent_tickets": 0,
"badges": {
"loyal": true,
"revenue": false,
"multi_service": true,
"experienced": true
},
"trust_score": {
"total": 50,
"label": "fair",
"services": 30,
"revenue": 5,
"age": 15,
"tickets": 0
}
}
}
```
#### Reading the Standout Note
get/api/v1/admin/clients/{id}/latest-note
`Clients/GetClientLatestNote` admin pinned first
Returns one of the client's notes: the pinned one if there is one, otherwise the newest.
Response fields data — 6
idintNote id.
contentstringThe note content.
pinnedboolWhether the note is pinned.
added_byintId of the admin who added it.
added_by_namestringName of the admin who added it.
created_atstringWhen the note was added.
Errors 2
not_found404No such client.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/clients/42/latest-note' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/clients/42/latest-note', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
// With no notes at all, data comes back null - not a 404.
if (body.data === null) return;
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/clients/42/latest-note');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
$response = Api::Clients()->GetClientLatestNote(['id' => 42]);
// On a client with no notes, 'data' is null.
$note = $response['data'] ?? null;
```
### Pitfalls
> **Amounts arrive raw, not formatted**
>
> The credit balance and revenue fields are numbers without a symbol, and the date is raw too. You read the currency from its own field and do the formatting yourself. That is deliberate: the server does not know the reader's locale.
> **A client with no notes returns null**
>
> On a client with no notes the standout-note endpoint returns `data: null`, not a `404`. Code that reaches straight into the fields breaks here, so check for empty first.
> **The trust score depends on your settings**
>
> The score in the summary is not a fixed scale; it is worked out from the tiers in your configuration. Change the tiers and the same client scores differently, so do not compare the score across installations.
### Related Articles
- [Client Endpoints](https://dev.wisecp.com/en/client-endpoints)
- [Client Configuration](https://dev.wisecp.com/en/client-configuration)
- [Client Internal Notes](https://dev.wisecp.com/en/client-internal-notes)
# API / Admin API / Finance
## Discount Coupons
https://dev.wisecp.com/en/discount-coupons
The seven endpoints that define discount coupons, copy them and set their conditions.
### Overview
Coupons are the **discount codes** a client uses in the basket or on an invoice. A coupon takes off either a share or a fixed amount. The type field names which of the two, and the matching field is the one to fill.
When a coupon is valid rests on **three things**: its stored status, its date range and its use limit. The listing folds the three together and returns the real state as well, and that is what a client meets.
The conditions cover the rest: which products, which cycles, which kind of client and the smallest basket it works on. The list of product values comes from an **endpoint of its own**.
### Reference
#### Listing the Coupons
get/api/v1/admin/financial/coupons
`Financial/GetCoupons` admin
Returns the discount coupons with the state they are really in.
Query 4
pageintWhich page.
limitintRecords per page. Clamped between one and a hundred.
searchstringSearches the code and the notes.
statusstringFilters by the real state: live, off, not yet started, expired or used up.
Response fields data[] — 15 + meta — 4
idintThe coupon id.
codestringThe code a client types in.
statusstringThe stored status: live or off.
effective_statusstringThe state it is really in. Worked out with the dates and the use limit taken in.
typestringThe discount type.
ratefloatThe share taken off.
amountfloatThe fixed amount taken off.
currency_idintThe currency of the fixed amount.
auto_applyboolWhether it applies itself.
max_usesintThe use limit.
usesintHow often it was used.
start_datestring | nullWhen it becomes valid.
due_datestring | nullWhen it stops being valid.
created_atstring | nullWhen it was created.
totalintHow many match the filter. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/coupons?status=active' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/financial/coupons');
url.searchParams.set('status', 'active');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/coupons?' . http_build_query(['status' => 'active']));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// There are two status fields: the stored one and the REAL one. Clients meet the second.
$rows = Api::Financial()->GetCoupons()['data'];
$live = array_filter($rows, fn ($c) => $c['effective_status'] === 'active');
```
#### Creating a Coupon
post/api/v1/admin/financial/coupons
`Financial/CreateCoupon` admin born live
Defines a new discount coupon.
Body 26
codestringreqThe code a client types in. It has to be unique on the installation.
typestringThe discount type: `percentage` or `amount`. A share by default.
ratefloatThe share taken off.
amountfloatThe fixed amount taken off.
currency_idintThe currency of the fixed amount.
product_servicesstring[]The products, categories, domain endings and add-ons the coupon applies to.
required_productsstring[]What the basket has to hold for the coupon to work.
validity_cyclesobjectThe billing cycles the coupon applies to.
required_product_cyclesobjectThe cycles the required products have to carry.
min_amountfloatThe smallest basket the coupon works on.
min_amount_currency_idintThe currency that smallest basket is in.
max_usesintHow many times it can be used. Zero means without limit.
recurringboolWhether the discount carries on into renewals.
recurring_numintHow many renewals it carries on.
auto_applyboolApplies itself to the basket.
apply_onceboolApplies once per client.
onetime_use_per_orderboolApplies once per order.
tax_freeboolCounts the discount as free of tax.
new_signups_onlyboolOpens it to new sign-ups alone.
existing_customers_onlyboolOpens it to existing clients alone.
dealership_onlyboolOpens it to resellers alone.
allow_mergeboolLets it stack with other coupons.
used_in_invoicesboolLets it be used on invoices too.
start_datestringWhen it becomes valid.
due_datestringWhen it stops being valid. Left empty, it never expires.
notesstringA note on the coupon.
Response fields 201 — data
dataobjectThe coupon created. Same shape as the detail endpoint.
Errors 4
code_required422The coupon code is empty.
coupon_save_failed422The code is taken, or the rate is not valid.
blocked_by_gate422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/financial/coupons' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"code":"HOSGELDIN30","type":"percentage","rate":30,"max_uses":50}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/coupons', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
code: 'WELCOME30',
type: 'percentage',
rate: 30,
max_uses: 50,
due_date: '2026-12-31',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/coupons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'code' => 'WELCOME30',
'type' => 'percentage',
'rate' => 30,
'max_uses' => 50,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A coupon is born LIVE, and with no end date it NEVER EXPIRES; weigh the two together.
Api::Financial()->CreateCoupon([
'code' => 'WELCOME30',
'rate' => 30,
'max_uses' => 50,
'due_date' => '2026-12-31',
]);
```
#### Reading the Product Tree
get/api/v1/admin/financial/coupons/products-hierarchy
`Financial/GetCouponProductsHierarchy` admin
Returns the products and categories a coupon can be tied to.
Response fields data
dataarrayA flat list of the products, categories, domain endings and add-ons you can pick. The values for the coupon fields come from here.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/coupons/products-hierarchy' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/coupons/products-hierarchy', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/coupons/products-hierarchy');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Do not write the values into your code: the list follows the installation's own products.
$options = Api::Financial()->GetCouponProductsHierarchy()['data'];
```
#### Reading One Coupon
get/api/v1/admin/financial/coupons/{id}
`Financial/GetCoupon` admin
Returns one coupon with all of its conditions.
Response fields data — 29
idintThe coupon id.
codestringThe code a client types in.
statusstringThe stored status.
typestringThe discount type.
ratefloatThe share taken off.
amountfloatThe fixed amount taken off.
currency_idintThe currency of the fixed amount.
product_servicesstring[]The products the coupon applies to.
validity_cyclesobjectThe billing cycles it applies to.
required_productsstring[]What the basket has to hold.
required_product_cyclesobjectThe cycles those have to carry.
min_amountfloatThe smallest basket.
min_amount_currency_idintThe currency that is in.
auto_applyboolWhether it applies itself.
max_usesintThe use limit.
usesintHow often it was used.
recurringboolWhether it carries on into renewals.
recurring_numintHow many renewals it lasts.
apply_onceboolWhether it applies once per client.
onetime_use_per_orderboolWhether it applies once per order.
tax_freeboolWhether the discount counts as free of tax.
new_signups_onlyboolWhether it is open to new sign-ups alone.
existing_customers_onlyboolWhether it is open to existing clients alone.
dealership_onlyboolWhether it is open to resellers alone.
allow_mergeboolWhether it stacks with other coupons.
used_in_invoicesboolWhether it can be used on invoices.
notesstringThe note on the coupon.
start_datestring | nullWhen it becomes valid.
due_datestring | nullWhen it stops being valid.
created_atstring | nullWhen it was created.
Errors 2
not_found404No such coupon.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/coupons/19' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/financial/coupons/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/coupons/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The detail carries NO real-state field; only the list works that out.
$coupon = Api::Financial()->GetCoupon(['id' => $id])['data'];
```
#### Updating a Coupon
patch/api/v1/admin/financial/coupons/{id}
`Financial/UpdateCoupon` admin
Changes the coupon fields you send.
Body 26
codestringThe code a client types in.
typestringThe discount type: `percentage` or `amount`. A share by default.
ratefloatThe share taken off.
amountfloatThe fixed amount taken off.
currency_idintThe currency of the fixed amount.
product_servicesstring[]The products, categories, domain endings and add-ons the coupon applies to.
required_productsstring[]What the basket has to hold for the coupon to work.
validity_cyclesobjectThe billing cycles the coupon applies to.
required_product_cyclesobjectThe cycles the required products have to carry.
min_amountfloatThe smallest basket the coupon works on.
min_amount_currency_idintThe currency that smallest basket is in.
max_usesintHow many times it can be used. Zero means without limit.
recurringboolWhether the discount carries on into renewals.
recurring_numintHow many renewals it carries on.
auto_applyboolApplies itself to the basket.
apply_onceboolApplies once per client.
onetime_use_per_orderboolApplies once per order.
tax_freeboolCounts the discount as free of tax.
new_signups_onlyboolOpens it to new sign-ups alone.
existing_customers_onlyboolOpens it to existing clients alone.
dealership_onlyboolOpens it to resellers alone.
allow_mergeboolLets it stack with other coupons.
used_in_invoicesboolLets it be used on invoices too.
start_datestringWhen it becomes valid.
due_datestringWhen it stops being valid. Left empty, it never expires.
notesstringA note on the coupon.
Response fields data
dataobjectThe coupon as it now stands. Same shape as the detail endpoint.
Errors 4
not_found404No such coupon.
coupon_save_failed422The code is taken, or the rate is not valid.
blocked_by_gate422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/financial/coupons/19' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"rate":25,"due_date":"2027-01-31"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/financial/coupons/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ rate: 25, due_date: '2027-01-31', auto_apply: true }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/coupons/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['rate' => 25, 'due_date' => '2027-01-31']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Changing the rate does not reach PAST orders; it touches later uses alone.
Api::Financial()->UpdateCoupon(['id' => $id, 'rate' => 25]);
```
#### Deleting a Coupon
delete/api/v1/admin/financial/coupons/{id}
`Financial/DeleteCoupon` admin
Removes a coupon.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the coupon removed.
Errors 2
not_found404No such coupon.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/financial/coupons/19' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/financial/coupons/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/coupons/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Switch it off rather than delete: the code stays taken and its history survives.
Api::Financial()->UpdateCoupon(['id' => $id, 'status' => 'inactive']);
```
#### Copying a Coupon
post/api/v1/admin/financial/coupons/{id}/duplicate
`Financial/DuplicateCoupon` admin the copy is born off
Opens a new coupon carrying an existing one's settings.
Body —
——No body is needed. The coupon comes from the path; send an empty body.
Response fields 201 — data
dataobjectThe copy created. Its code gains a copy suffix, its status is off, its use count is cleared and its start date is dropped.
Errors 2
not_found404No such coupon.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/financial/coupons/19/duplicate' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/financial/coupons/${id}/duplicate`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.code); // WELCOME30-COPY
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/coupons/' . $id . '/duplicate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The copy is born OFF: fix its code and dates, then switch it on yourself.
$copy = Api::Financial()->DuplicateCoupon(['id' => $id])['data'];
Api::Financial()->UpdateCoupon([
'id' => $copy['id'], 'code' => 'SUMMER30', 'status' => 'active',
]);
```
### Pitfalls
> **There are two status fields**
>
> The stored status is the switch an operator flips. The **real state** is worked out with the date range and the use limit. A coupon that reads live may not work because it expired or was used up. The second field is what tells you what a client will meet, and it comes back on the listing alone.
> **With no end date a coupon never expires**
>
> A coupon left without an end date **never stops**. A code opened for a campaign and forgotten still takes money off months later. With the use limit at zero as well it is both endless and unlimited. Fill in at least one of the two on a campaign code.
> **A copy is born off and under a new code**
>
> The duplicate endpoint opens the new coupon **switched off**. It also adds a copy suffix to the code, clears the use count and drops the start date. The copy is not ready to use: fix its code and switch it on. Duplicating the same coupon twice numbers the suffix upward.
> **A change does not reach the past**
>
> Changing a coupon's rate or its conditions touches **later uses**. Orders and invoices already cut with it keep the old rate. That is right, because those documents tell the story of a moment. Correcting a mistake means going to the invoice itself as well.
> **The product values belong to the installation**
>
> The values naming which products a coupon applies to come from a **separate endpoint** and follow the installation's own product tree. Writing them into your code leaves a coupon quietly matching nothing on another installation, or once the products change. Read the list each time.
### Related Articles
- [Currencies and Rates](https://dev.wisecp.com/en/currencies-and-rates)
- [Taxation Rules](https://dev.wisecp.com/en/taxation-rules)
- [Managing Invoices](https://dev.wisecp.com/en/managing-invoices)
## Currencies and Rates
https://dev.wisecp.com/en/currencies-and-rates
The eight endpoints for the currencies, their rates and the rate provider.
### Overview
An installation has one **base currency**, and the others carry their rate against it. Prices, invoices and reports all convert through that point.
Rates are either written by hand or come from a **provider module**. You pick the provider and set how often it runs, and a scheduled task refreshes the rates. An endpoint for pulling them by hand sits alongside.
A currency can be **tied to countries**: a visitor's country decides which one they see. A country belongs to one currency at a time.
### Reference
#### Listing the Currencies
get/api/v1/admin/financial/currencies
`Financial/GetCurrencies` admin
Returns every currency on the installation with its rate.
Response fields data[] — 13
idintThe currency id.
codestringIts international code.
namestringThe currency name.
statusstringWhether it is live or off.
localboolWhether it is the installation's own. Every conversion runs through it.
hiddenboolWhether clients get to see it.
ratefloatIts rate against the installation's own.
formatintHow the number gets formatted.
prefixstringThe mark that goes before the amount.
suffixstringThe mark that goes after the amount.
countrystringIts default country.
countriesstring[]The countries tied to it. A visitor's country picks it.
modulesstring[]The payment methods working in it.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/currencies' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/currencies', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const base = data.find((c) => c.local);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currencies');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Rates run against the BASE currency; converting between two others passes through it.
$all = Api::Financial()->GetCurrencies()['data'];
$base = current(array_filter($all, fn ($c) => $c['local']));
```
#### Reading the Rate Settings
get/api/v1/admin/financial/currency-settings
`Financial/GetCurrencySettings` admin
Returns which provider supplies the rates and how often they refresh.
Response fields data — 5
modulestringThe module supplying the rates.
auto_rate_enabledboolWhether the rates refresh by themselves.
update_periodstringHow often they refresh: hourly or daily.
last_run_atstring | nullWhen they last refreshed.
available_modulesstring[]The rate providers installed.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/currency-settings' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/currency-settings', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currency-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// An OLD last-run time means stale rates; the refresh may have quietly stopped.
$s = Api::Financial()->GetCurrencySettings()['data'];
```
#### Writing the Rate Settings
put/api/v1/admin/financial/currency-settings
`Financial/UpdateCurrencySettings` admin
Changes the rate provider and how the refresh runs.
Body 4
modulestringThe rate provider to use.
auto_rate_enabledboolLets the rates refresh by themselves.
update_periodstringHow often they refresh. Daily by default.
module_dataobjectThe provider's own settings.
Response fields data — 5
dataobjectThe settings as they now stand. Same shape as the read endpoint.
Errors 2
module_not_found422No such provider.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/financial/currency-settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"module":"WAtlas","auto_rate_enabled":true,"update_period":"day"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/currency-settings', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
module: 'WAtlas',
auto_rate_enabled: true,
update_period: 'day',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currency-settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'module' => 'WAtlas',
'auto_rate_enabled' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Put a provider through the test endpoint BEFORE switching; a bad key gives quiet staleness.
Api::Financial()->TestCurrencyModule(['module' => 'WAtlas']);
Api::Financial()->UpdateCurrencySettings(['module' => 'WAtlas']);
```
#### Testing the Provider
post/api/v1/admin/financial/currency-modules/test
`Financial/TestCurrencyModule` admin it saves nothing
Tests a rate provider by pulling a sample rate from it.
Body 2
modulestringreqThe provider to test.
module_dataobjectSettings to test with. They are not saved and serve this call alone.
Response fields data — 2
localstringThe base currency code.
ratesobjectThe sample rates the provider returned.
Errors 6
module_required422No provider name was given.
module_not_found422No such provider.
not_supported422The provider supplies no rates.
no_local422No base currency is set.
test_failed422The provider returned no rate at all.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/financial/currency-modules/test' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"module":"WAtlas"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/currency-modules/test', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ module: 'WAtlas' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currency-modules/test');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['module' => 'WAtlas']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The test connects LIVE and saves nothing; a provider not yet chosen can be tried too.
$r = Api::Financial()->TestCurrencyModule([
'module' => 'WAtlas',
'module_data' => ['WAtlas' => ['api_key' => $key]],
])['data'];
```
#### Refreshing the Rates
post/api/v1/admin/financial/currencies/sync
`Financial/SyncCurrencyRates` admin it runs on the spot
Pulls the rates from the provider by hand.
Body —
——No body is needed. The provider and the period come from the currency settings, not from the call, so send an empty body.
Response fields data — 3
rates_changedboolWhether the rates moved.
reasonstringWhy nothing moved. It comes back only when the refresh was skipped.
last_run_atstring | nullWhen the refresh happened.
Errors 2
sync_failed422The rates could not be pulled.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/financial/currencies/sync' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/currencies/sync', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
if (! data.rates_changed) console.warn(data.reason);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currencies/sync');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A successful call does not mean the rates MOVED; read the reason field.
$r = Api::Financial()->SyncCurrencyRates()['data'];
if (! $r['rates_changed']) error_log($r['reason'] ?? 'skipped');
```
#### Reading One Currency
get/api/v1/admin/financial/currencies/{id}
`Financial/GetCurrency` admin
Returns a single currency.
Response fields data — 13
idintThe currency id.
codestringIts international code.
namestringThe currency name.
statusstringWhether it is live or off.
localboolWhether it is the installation's own. Every conversion runs through it.
hiddenboolWhether clients get to see it.
ratefloatIts rate against the installation's own.
formatintHow the number gets formatted.
prefixstringThe mark that goes before the amount.
suffixstringThe mark that goes after the amount.
countrystringIts default country.
countriesstring[]The countries tied to it. A visitor's country picks it.
modulesstring[]The payment methods working in it.
Errors 2
not_found404No such currency.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/currencies/4' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/financial/currencies/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currencies/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The base currency's rate is ALWAYS one; trying to change it means nothing.
$c = Api::Financial()->GetCurrency(['id' => $id])['data'];
```
#### Updating a Currency
patch/api/v1/admin/financial/currencies/{id}
`Financial/UpdateCurrency` admin it can move the base
Changes a currency's look, its rate and what it is tied to.
Body 9
namestringThe currency name.
prefixstringThe mark that goes before the amount.
suffixstringThe mark that goes after the amount.
formatintHow the number gets formatted.
ratefloatIts rate against the base. With the refresh on, the next run writes over it.
hiddenboolKeeps it from clients.
countriesstring[]The countries to tie to it. A country can belong to one currency alone.
modulesstring[]The payment methods that work in it.
localboolMakes this the installation's base currency. The point every conversion rests on moves.
Response fields data — 13
dataobjectThe currency as it now stands. Same shape as the detail endpoint.
Errors 4
not_found404No such currency.
country_conflict422The country belongs to another currency.
currency_save_failed422The record could not be written.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/financial/currencies/4' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"US Dollar","prefix":"$","hidden":false}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/financial/currencies/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name: 'US Dollar', prefix: '$', hidden: false }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currencies/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['name' => 'US Dollar', 'prefix' => '$']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Do not read the base field as ONE MORE switch: it moves the installation's money base
// and every rate is worked out again.
Api::Financial()->UpdateCurrency(['id' => $id, 'prefix' => '$']);
```
#### Switching a Currency On and Off
put/api/v1/admin/financial/currencies/{id}/status
`Financial/SetCurrencyStatus` admin
Decides whether a currency can be used at all.
Body 1
statusboolreqSwitches the currency on or off.
Response fields data — 13
dataobjectThe currency as it now stands. Same shape as the detail endpoint.
Errors 4
not_found404No such currency.
local_currency422The base currency cannot be switched off.
blocked_by_gate422A hook refused the change.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/financial/currencies/4/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":true}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/financial/currencies/${id}/status`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: true }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/currencies/' . $id . '/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['status' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Switching off leaves PAST invoices in that currency alone; it stops new choices.
Api::Financial()->SetCurrencyStatus(['id' => $id, 'status' => false]);
```
### Pitfalls
> **Moving the base currency shifts everything**
>
> The base-currency field in the update body is no ordinary option. It **moves the installation's money base**, writes to the settings file and has every rate worked out again. Prices keep the same numbers while now meaning a different unit. Sending this field by accident is among the costliest mistakes here.
> **A rate written by hand goes at the next refresh**
>
> With the refresh on, writing a rate by hand is a **passing** correction: the provider writes over it on the next run. For a rate that holds, switch the refresh off first. This is why a rate seems to "come back" after being set by hand.
> **A successful refresh does not mean the rates moved**
>
> The refresh endpoint counts as **successful** even when it returns without pulling anything, and names the reason in a separate field. The provider may not have answered, the interval may not have passed, or the setting may be off. Monitoring that reads only the response code will not notice rates gone stale for months.
> **A country belongs to one currency**
>
> Tying a country to a currency while it sits on another gets the call **refused**. The country list replaces what was there, so a country left out drops its tie. When changing them, read the current list and add to it.
> **Test a provider before choosing it**
>
> The test endpoint **opens a live connection and saves nothing**. A provider not yet chosen can be tried with settings passed in. Switching provider without testing leaves the rates quietly unrefreshed. No error shows, and only the last-run time gives it away by standing still.
### Related Articles
- [Taxation Rules](https://dev.wisecp.com/en/taxation-rules)
- [Discount Coupons](https://dev.wisecp.com/en/discount-coupons)
- [Managing Invoices](https://dev.wisecp.com/en/managing-invoices)
## Taxation Rules
https://dev.wisecp.com/en/taxation-rules
The seven endpoints for tax rates, country rules and the invoice document settings.
### Overview
Tax is built in three layers. At the bottom sit the **basic settings**. They say whether tax is on, what the default rate is, and where the tax sits.
Above them stand the **country and state rules**. When a rule matches a client's address the rate comes from there. A state rule comes before a country rule, and a country rule before the default.
A separate group covers the **invoice document itself**. It shapes the numbering, opens or closes formalising, names the tax fields a company client is asked for, and handles posting a printed bill.
### Reference
#### Reading the Tax Settings
get/api/v1/admin/financial/taxation
`Financial/GetTaxation` admin
Returns whether tax is on, its rate and how it is worked out.
Response fields data — 4
enabledboolWhether tax is on.
ratefloatThe default tax rate.
taxation_typestringWhether tax sits inside the amount or on top of it.
send_bill_to_addressobjectPosting a printed bill: whether it is on, its charge and its currency.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/taxation' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/taxation', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/taxation');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The rate here is the DEFAULT; a rule set for the client's country comes first.
$t = Api::Financial()->GetTaxation()['data'];
```
#### Writing the Tax Settings
put/api/v1/admin/financial/taxation
`Financial/UpdateTaxation` admin
Switches tax on and writes its rate and how it is worked out.
Body 3
enabledboolSwitches tax on or off.
ratefloatThe default tax rate.
taxation_typestringWhether tax sits inside the amount or on top of it.
Response fields data — 4
dataobjectThe tax settings as they now stand. Same shape as the read endpoint.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/financial/taxation' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true,"rate":20,"taxation_type":"exclusive"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/taxation', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
enabled: true,
rate: 20,
taxation_type: 'exclusive',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/taxation');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => true, 'rate' => 20]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Changing how tax is worked out turns the SAME price into a different total; think again
// about what the prices you advertise are meant to say.
Api::Financial()->UpdateTaxation(['taxation_type' => 'inclusive']);
```
#### Reading the Advanced Settings
get/api/v1/admin/financial/taxation/advanced
`Financial/GetTaxationAdvanced` admin
Returns the settings for invoice numbering and the company tax fields.
Response fields data — 18
invoice_show_requires_loginboolWhether seeing an invoice needs signing in.
payment_commission_taxboolWhether the payment commission and the instalment surcharge carry the invoice's rate.
delete_invoice_item_aocboolWhether an invoice line can be removed.
invoice_formalization_statusboolWhether formalising is available.
firstly_create_invoiceboolWhether the invoice is cut before the order.
balance_taxationstringHow topping up the balance gets taxed.
invoice_special_notestringA note put on every invoice.
pdf_fontstringThe typeface used in the document.
invoice_number_formatstringThe invoice number's shape. It has to carry the placeholder marking where the number goes.
invoice_number_format_statusboolWhether that shape is used.
paid_invoice_number_formatstringThe paid-invoice number's shape.
paid_invoice_number_format_statusboolWhether that shape is used.
invoice_incrementintThe number invoice numbering starts from.
paid_invoice_incrementintThe number paid-invoice numbering starts from.
send_bill_to_addressobjectPosting a printed bill: whether it is on, its charge and its currency.
company_tax_officeobjectThe tax office field: whether it shows and whether it is required.
company_tax_numberobjectThe tax number field: whether it shows, whether it is required and whether it is checked.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/taxation/advanced' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/taxation/advanced', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/taxation/advanced');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// There are two numbering series: one for invoices and one for PAID invoices.
$a = Api::Financial()->GetTaxationAdvanced()['data'];
```
#### Writing the Advanced Settings
put/api/v1/admin/financial/taxation/advanced
`Financial/UpdateTaxationAdvanced` admin
Changes the advanced tax and invoice settings you send.
Body 18
invoice_show_requires_loginboolWhether seeing an invoice needs signing in.
payment_commission_taxboolWhether the payment commission and the instalment surcharge carry the invoice's rate.
delete_invoice_item_aocboolWhether an invoice line can be removed.
invoice_formalization_statusboolWhether formalising is available.
firstly_create_invoiceboolWhether the invoice is cut before the order.
balance_taxationstringHow topping up the balance gets taxed.
invoice_special_notestringA note put on every invoice.
pdf_fontstringThe typeface used in the document.
invoice_number_formatstringThe invoice number's shape. It has to carry the placeholder marking where the number goes.
invoice_number_format_statusboolWhether that shape is used.
paid_invoice_number_formatstringThe paid-invoice number's shape.
paid_invoice_number_format_statusboolWhether that shape is used.
invoice_incrementintThe number invoice numbering starts from.
paid_invoice_incrementintThe number paid-invoice numbering starts from.
send_bill_to_addressobjectPosting a printed bill: whether it is on, its charge and its currency.
company_tax_officeobjectThe tax office field: whether it shows and whether it is required.
company_tax_numberobjectThe tax number field: whether it shows, whether it is required and whether it is checked.
Response fields data — 18
dataobjectThe settings as they now stand. Same shape as the read endpoint.
Errors 2
invalid_number_format422The number format carries no placeholder.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/financial/taxation/advanced' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"invoice_number_format":"FTR-{NUMBER}","invoice_number_format_status":true}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/taxation/advanced', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
invoice_number_format: 'INV-{NUMBER}',
invoice_number_format_status: true,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/taxation/advanced');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'invoice_number_format' => 'INV-{NUMBER}',
'invoice_number_format_status' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Lowering the numbering START can hand the same number out twice; do not drop below
// the highest number already given.
Api::Financial()->UpdateTaxationAdvanced(['invoice_increment' => 1000]);
```
#### Listing the Tax Rules
get/api/v1/admin/financial/tax-rules
`Financial/GetTaxRules` admin
Returns the tax rates set by country and state.
Response fields data[] — 7
country_idintThe country id.
country_namestringThe country name.
ccstringThe two-letter country code.
state_idintThe state id. Zero says the rule covers the whole country.
state_namestringThe state name.
tax_ratefloatThe total rate. The parts added together.
ratesobject[]The parts making up the rate: each with its name and value.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/financial/tax-rules' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/tax-rules', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/tax-rules');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A state rule comes before the COUNTRY rule; with neither, the default rate applies.
$rules = Api::Financial()->GetTaxRules()['data'];
```
#### Writing a Tax Rule
put/api/v1/admin/financial/tax-rules
`Financial/UpdateTaxRule` admin
Writes the tax rate for a country or a state.
Body 4
country_idintreqThe country the rule covers.
state_idintThe state the rule covers. Zero means the whole country.
state_namestringThe name of a new state. Given, the state is created first.
ratesobject[]The parts making up the rate: each with its name and value.
Response fields data — 3
country_idintThe rule's country.
state_idintThe rule's state. A newly created state comes back with its id here.
ratefloatThe total rate worked out.
Errors 5
invalid_country422The country is not valid.
state_insert_failed422The new state could not be created.
tax_rule_failed422The rule could not be written.
blocked_by_gate422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/financial/tax-rules' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"country_id":792,"state_id":0,"rates":[{"name":"KDV","value":20}]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/tax-rules', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
country_id: 840,
state_id: 0,
rates: [{ name: 'VAT', value: 20 }],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/tax-rules');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'country_id' => 840,
'rates' => [['name' => 'VAT', 'value' => 20]],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The parts REPLACE what was there: your list clears the old one rather than adding.
Api::Financial()->UpdateTaxRule([
'country_id' => 840,
'rates' => [['name' => 'VAT', 'value' => 20]],
]);
```
#### Defining the European Rates
post/api/v1/admin/financial/tax-rules/define-all
`Financial/DefineAllTaxRates` admin it writes over existing rules
Defines the value-added tax rates of the European Union countries at once.
Body —
——No body is needed. The rate set is built in rather than sent, so there is nothing to pick; send an empty body.
Response fields data — 1
definedintHow many rates were defined.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/financial/tax-rules/define-all' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/financial/tax-rules/define-all', {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.defined);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/financial/tax-rules/define-all');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// If the installation's own country is on the list the DEFAULT rate moves; keep the old
// rules first.
$before = Api::Financial()->GetTaxRules()['data'];
Api::Financial()->DefineAllTaxRates();
```
### Pitfalls
> **A rate can come from three places**
>
> The rate on an invoice comes first from the client's **state rule**. Failing that it comes from the **country rule**, and only then from the default. Changing the default moves nothing for clients in countries that carry a rule. That is usually behind a "the rate update did nothing" report.
> **The rule parts replace what was there**
>
> When writing a tax rule the list of parts you send **replaces** what was there rather than adding to it. To add a second part to a country, read the current list and send both together. Sending one part quietly drops the others.
> **The bulk define writes over existing rules**
>
> Defining the European rates in bulk **writes over the rules you entered by hand** for those countries. When the installation's own country is among them, the default rate moves as well. Read and keep the current rules before running it, because there is no other way back.
> **Lowering the numbering start causes clashes**
>
> Dropping the invoice numbering start **below the highest number already given** hands the same number out twice. Two documents sharing a number is a serious matter in accounting and hard to put right afterwards. Move the start upward alone.
> **How tax is worked out changes the total**
>
> Whether tax sits inside the amount or on top of it changes **what your advertised prices say**. Inside, an item marked a hundred sells for a hundred with the tax taken out of it. On top, the client pays a hundred and twenty. Changing this once an installation is live means going back over the whole price list.
### Related Articles
- [Currencies and Rates](https://dev.wisecp.com/en/currencies-and-rates)
- [Discount Coupons](https://dev.wisecp.com/en/discount-coupons)
- [Managing Invoices](https://dev.wisecp.com/en/managing-invoices)
# API / Admin API / Invoices
## Managing Invoices
https://dev.wisecp.com/en/managing-invoices
The six endpoints that issue, read and edit invoices and give the revenue summary.
### Overview
These six endpoints deal with the **invoice itself**: listing, issuing, reading, editing its header fields and deleting it. A revenue summary giving a period total sits alongside them.
An invoice carries a **snapshot**: the client's name, address and tax details are held inside the record as they stood at issue. A client changing their address later leaves the invoice untouched, because a document once issued tells the story of a moment.
The money has three layers: the **lines** give the subtotal, the **tax** what sits on top of it, and the **commission and surcharge** what the payment method brought. Together the three make the grand total.
### Reference
#### Listing the Invoices
get/api/v1/admin/invoices
`Invoices/GetInvoices` admin
Returns invoices, filtered and paged.
Query 15
pageintWhich page.
limitintRecords per page. A value out of range falls back to the default.
searchstringSearches the invoice number and the client details.
statusstringFilters by status: `waiting`, `unpaid`, `paid`, `cancelled`, `refund`. It also takes derived filters such as overdue, upcoming, formalised and not formalised.
client_idintFilters by client.
currency_idintFilters by currency.
taxedboolSeparates the formalised ones.
amountstringFilters by amount.
amount_opstringWhich way the amount comparison runs.
item_descriptionstringSearches the line descriptions.
cdatestringFilters by the date issued.
cdate_opstringWhich way that comparison runs.
duedatestringFilters by the due date.
duedate_opstringWhich way that comparison runs.
daterangestringFilters between two dates. Its direction comes from its own comparison field.
Response fields data[] — 14 + meta — 4
idintThe invoice id.
numberstring | nullThe invoice number. Empty until a number is given.
statusstringThe invoice status: `waiting`, `unpaid`, `paid`, `cancelled`, `refund`.
currency_idintThe invoice currency.
subtotalfloatThe subtotal.
taxfloatThe tax.
totalfloatThe grand total.
formalizedboolWhether it was turned into a formal invoice.
payment_methodstring | nullThe payment method.
created_atstring | nullWhen it was issued.
due_datestring | nullWhen it falls due.
paid_atstring | nullWhen it was paid.
refund_datestring | nullWhen it was refunded.
clientobjectThe client: id, name, company and e-mail. As they stood when the invoice was issued.
total intHow many match the filter. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices?status=unpaid&limit=25' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/invoices');
url.searchParams.set('status', 'unpaid');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices?' . http_build_query(['status' => 'unpaid', 'limit' => 25]));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Draft and system invoices NEVER enter this list; the count will not match the table.
$rows = Api::Invoices()->GetInvoices([], ['status' => 'unpaid'])['data'];
```
#### Issuing an Invoice
post/api/v1/admin/invoices
`Invoices/CreateInvoice` admin the notice is optional
Issues an invoice to a client by hand and writes its lines.
Body 8
client_idintreqThe client the invoice goes to.
itemsarrayreqThe invoice lines. At least one line is needed.
currency_idintThe invoice currency. Left out, the client's own is used.
statusstringThe status it opens with. Unpaid by default.
payment_methodstringThe payment method.
created_atstringThe date issued. Left out, the moment of the call is used.
due_datestringThe due date. Left out, the end of today is used.
send_notificationboolSends the client the notice that suits the status.
Line fields items[] — 8
descriptionstringreqWhat the line is for.
quantityintreqHow many. One at the least.
amountfloatreqThe unit amount.
discountfloatThe discount value.
discount_typestringWhether the discount is an amount or a share.
tax_ratefloatA tax rate for this line.
tax_exemptboolKeeps the line free of tax.
user_pidintThe service it belongs to. Zero says the line stands alone.
Response fields 201 — data
dataobjectThe invoice issued. Same shape as the detail endpoint.
Errors 6
invalid_client422No client was given.
not_found404No such client.
currency_required422No currency could be resolved.
items_required422No line was given.
create_failed422The invoice could not be issued.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"client_id":87,"currency_id":840,"items":[{"description":"Hosting","quantity":1,"amount":12.5}]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/invoices', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
client_id: 87,
currency_id: 840,
due_date: '2026-07-01',
items: [
{ description: 'Hosting Plan', quantity: 1, amount: 12.5 },
],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'client_id' => 87,
'currency_id' => 840,
'items' => [
['description' => 'Hosting Plan', 'quantity' => 1, 'amount' => 12.5],
],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The notice is OPTIONAL: leave it out and the client never hears about the invoice.
Api::Invoices()->CreateInvoice([
'client_id' => $uid,
'items' => $lines,
'send_notification' => true,
]);
```
#### Reading the Revenue Summary
get/api/v1/admin/invoices/stats
`Invoices/GetInvoiceStats` admin
Returns the total for the type and period you pick.
Query 2
typestringWhat gets added up: unpaid, paid, overdue or tax. The unpaid ones by default.
periodstringWhich period: the last seven days, the last fifteen, this month, last month, this year or last year. This month by default.
Response fields data — 5
typestringThe type applied.
periodstringThe period applied.
amountfloatThe total. A raw number, with other currencies converted into the local one before adding.
countintHow many invoices went into it.
currency_idintThe currency the total is in.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/stats?type=unpaid&period=this-month' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/invoices/stats');
url.searchParams.set('type', 'unpaid');
url.searchParams.set('period', 'this-month');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/stats?' . http_build_query(['type' => 'unpaid', 'period' => 'this-month']));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The amount is a CONVERTED total, worked out at the day's rate, and you format it yourself.
$s = Api::Invoices()->GetInvoiceStats([], ['type' => 'unpaid'])['data'];
$sum = Money::formatter_symbol($s['amount'], $s['currency_id']);
```
#### Reading One Invoice
get/api/v1/admin/invoices/{id}
`Invoices/GetInvoice` admin
Returns an invoice with its lines, payments and the client snapshot.
Response fields data — 33
idintThe invoice id.
numberstring | nullThe invoice number.
statusstringThe invoice status: `waiting`, `unpaid`, `paid`, `cancelled`, `refund`.
currency_idintThe invoice currency.
created_atstring | nullWhen it was issued.
due_datestring | nullWhen it falls due.
paid_atstring | nullWhen it was paid.
refund_datestring | nullWhen it was refunded.
subtotalfloatThe subtotal.
taxfloatThe tax. Commission and surcharge taxes do not enter here.
additional_taxfloatThe additional tax.
totalfloatThe grand total.
total_paidfloatWhat was paid, worked out from the payment records.
balancefloatWhat remains owing.
tax_ratefloatThe tax rate.
taxation_typestringWhether tax sits inside the amount or outside it.
formalizedboolWhether it was turned into a formal invoice.
taxfreeboolWhether it is free of tax.
localboolWhether it is a local invoice.
recurringboolWhether it repeats.
recurring_timeintHow often it repeats.
recurring_periodstringThe period it repeats over.
payment_methodstring | nullThe payment method.
payment_method_statusstring | nullThe state of the payment method.
payment_method_dataobjectWhat the payment method carries with it.
payment_method_commissionfloatThe payment commission.
payment_method_commission_ratefloatThe commission rate.
payment_method_commission_taxfloatThe tax on the commission. It enters the grand total and not the tax field.
installment_surchargefloatThe instalment surcharge.
installment_surcharge_taxfloatThe tax on the surcharge. This too enters the grand total and not the tax field.
installment_countintHow many instalments.
send_bill_to_addressfloatThe charge for posting the bill.
notesstringThe note on the invoice.
unreadboolWhether the client has yet to read it.
exchange_ratefloatThe rate at the time of issue.
discountsobjectThe discount lines and their total.
user_dataobjectThe client and their address as they stood at issue.
clientobjectThe client: id, name, company and e-mail.
itemsarrayThe invoice lines.
paymentsarrayThe payment records.
Line fields items[] — 17
idintThe line id.
parent_idintThe parent line. Sub-lines hang off a line above.
owner_idintThe invoice it belongs to.
client_idintThe client.
service_idintThe service it covers. Zero says the line stands alone.
descriptionstringWhat the line is for.
quantityintHow many.
tax_exemptboolWhether it is free of tax.
tax_ratefloatThe line's tax rate. Minus one says the rate comes from the invoice.
additional_taxesarrayThe extra taxes on the line.
additional_tax_totalfloatWhat those add up to.
amountfloatThe unit amount.
total_amountfloatThe line total. Quantity times amount, less the discount.
currency_idintThe line currency.
due_datestring | nullThe end of the line's period.
rankintWhere it sits on the invoice.
optionsarrayExtra details on the line.
Payment fields payments[] — 14
idintThe payment id.
amount_infloatWhat came in.
amount_outfloatWhat went out.
feesfloatThe fee taken.
currency_idintThe payment currency.
ratefloatThe rate at the time of payment.
payment_methodstring | nullThe payment method.
transaction_idstring | nullThe transaction number.
descriptionstringWhat the payment was.
paid_atstring | nullWhen it was paid.
created_atstring | nullWhen the record was made.
created_byintThe staff member who made it.
recorded_bystring | nullTheir name.
ipstring | nullThe address it came from.
Errors 2
not_found404No such invoice.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/1212' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// When REBUILDING the total, add the two taxes yourself; the tax field leaves them out.
$inv = Api::Invoices()->GetInvoice(['id' => $id])['data'];
$sum = $inv['subtotal'] + $inv['tax']
+ $inv['payment_method_commission'] + $inv['payment_method_commission_tax']
+ $inv['installment_surcharge'] + $inv['installment_surcharge_tax'];
```
#### Editing an Invoice
patch/api/v1/admin/invoices/{id}
`Invoices/UpdateInvoice` admin
Changes an invoice's header fields, recomputing the totals when needed.
Body 11
numberstringThe invoice number.
payment_methodstringThe payment method.
taxation_typestringWhether tax sits inside the amount. Changing it recomputes the totals.
currency_idintThe invoice currency. Changing it recomputes the totals.
tax_ratefloatThe tax rate.
formalizedboolTurns it into a formal invoice. The first time it does, the client is told.
taxfreeboolMakes the invoice free of tax. It takes precedence over formalising.
created_atstringThe date issued.
due_datestringThe due date.
paid_atstringThe date paid.
refund_datestringThe date refunded.
Response fields data
dataobjectThe invoice as it now stands. Same shape as the detail endpoint.
Errors 2
not_found404No such invoice.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/invoices/1212' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"number":"INV-2026-0042","tax_rate":20}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
number: 'INV-2026-0042',
tax_rate: 20,
due_date: '2026-07-15 23:59:00',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'number' => 'INV-2026-0042',
'tax_rate' => 20,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Making it tax-free OVERRIDES formalising; sending both together makes no sense.
Api::Invoices()->UpdateInvoice(['id' => $id, 'formalized' => true]);
```
#### Deleting an Invoice
delete/api/v1/admin/invoices/{id}
`Invoices/DeleteInvoice` admin unwinds a chain of records
Removes an invoice and every record hanging off it.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the invoice removed.
Errors 3
not_found404No such invoice.
blocked_by_gate422A hook refused the delete.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/invoices/1226' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Cancel it rather than delete: the accounting trail stays and it leaves what is owed.
Api::Invoices()->SetInvoiceStatus(['id' => $id, 'status' => 'cancelled']);
```
### Pitfalls
> **The tax field does not hold every tax**
>
> The taxes on the payment commission and the instalment surcharge **enter the grand total and not the tax field**. Add the subtotal to the tax expecting the grand total and the difference has no obvious source. Rebuilding the total means adding those two taxes from their own fields.
> **Draft invoices are not in the list**
>
> The listing endpoint **hides** draft and system invoices. That matches what the panel shows, yet the count from the list will not match the rows in the database. Weigh that when writing an accounting report; adding a filter does not bring the hidden ones back.
> **Formal and tax-free share one field**
>
> An invoice's tax state is one field taking one of three values: normal, formal or tax-free. Making it tax-free **overrides** formalising, and sending both together means nothing. The first time formalising is applied, the client is told as well.
> **A delete unwinds the chain**
>
> Deleting an invoice does more than remove the record: it also **unwinds** the lines, the income and expense entries, the links to services and any pending metered rows. A hook can refuse the delete, because some invoices leaving would break the books. To back out, cancel rather than delete: the trail stays and the debt goes.
> **Empty dates come back empty**
>
> Fields for things that have not happened, such as the paid and refund dates, come back **empty**. The database keeps placeholder dates there and the response clears them. Check a date exists before reading it, or you end up with a screen treating a placeholder as real.
### Related Articles
- [Invoice Items and Payments](https://dev.wisecp.com/en/invoice-items-and-payments)
- [Invoice Status and Notices](https://dev.wisecp.com/en/invoice-status-and-notices)
- [Cash Records](https://dev.wisecp.com/en/cash-records)
## Invoice Status and Notices
https://dev.wisecp.com/en/invoice-status-and-notices
The five endpoints for an invoice's status, its client details and the notices sent.
### Overview
These five endpoints run the **life** of an invoice once issued. They change its status, correct the client details, send a notice, formalise it and remind.
The status change is the **heaviest** thing here. Marking an invoice paid opens an income entry, gives it a paid-invoice number and sets the linked services moving; refunding winds that back and can order a refund through the payment module.
Three of the endpoints **mail the client**: the notice, the reminder and, when its file is there, formalising. Calling them from a script reaches real people.
### Reference
#### Changing the Status
put/api/v1/admin/invoices/{id}/status
`Invoices/UpdateInvoiceStatus` admin it has side effects
Changes an invoice's status and carries out what that status brings.
Body 5
statusstringreqThe new status: `paid`, `unpaid`, `refund` or `cancelled`.
payment_methodstringThe payment method. On a paid invoice, sending this alone changes the method.
refund_methodstringHow the refund happens. It can go back through the payment module.
cancel_servicesboolCancels the services on the invoice as well. It works on refund and cancel.
notifyboolTells the client.
Response fields data
dataobjectThe invoice as it now stands. Same shape as the detail endpoint.
Errors 5
not_found404No such invoice.
invalid_status422The status is not recognised.
same_status422The invoice already stands there.
blocked_by_gate422A hook refused the change.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/invoices/1212/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"paid","payment_method":"Balance","notify":true}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/status`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
status: 'paid',
payment_method: 'Balance',
notify: true,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'status' => 'paid',
'payment_method' => 'Balance',
'notify' => true,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Marking it paid OPENS AN INCOME ENTRY, gives a number and sets the services moving.
Api::Invoices()->UpdateInvoiceStatus([
'id' => $id,
'status' => 'paid',
'notify' => true,
]);
```
#### Correcting the Client Details
patch/api/v1/admin/invoices/{id}/client-details
`Invoices/UpdateInvoiceClientDetails` admin this invoice only
Corrects the client and address details frozen onto an invoice.
Body 10
kindstringWhether the client is a person or a company. On a person the company name is cleared.
first_namestringThe first name. The full name is built from it.
last_namestringThe last name.
emailstringThe e-mail address.
phonestringThe phone.
identitystringThe identity or tax number.
company_namestringThe company name. It applies to a company.
tax_numberstringThe tax number.
tax_officestringThe tax office.
addressobjectThe address: street, country, state, city and postcode. State and city are resolved from an id when given as a number and stored as written when given as text.
Response fields data
dataobjectThe invoice as it now stands. Same shape as the detail endpoint.
Errors 2
not_found404No such invoice.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/invoices/1212/client-details' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"kind":"corporate","company_name":"Ornek A.S.","tax_number":"0000000000"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/client-details`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
kind: 'corporate',
company_name: 'Example Inc.',
tax_number: '000000000',
address: { detail: '123 Market Street', country_id: 840, zipcode: '94105' },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/client-details');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'kind' => 'corporate',
'company_name' => 'Example Inc.',
'tax_number' => '000000000',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This endpoint DOES NOT TOUCH the live client; it corrects the copy on this invoice.
Api::Invoices()->UpdateInvoiceClientDetails([
'id' => $id,
'company_name' => 'Example Inc.',
]);
```
#### Sending a Notice
post/api/v1/admin/invoices/{id}/notifications
`Invoices/SendInvoiceNotification` admin a real e-mail goes out
Sends the client the invoice notice template you pick.
Body 1
templatestringreqThe key of the template to send. It has to be one of the invoice notices and switched on.
Response fields data — 3
sentboolWhether the send ran.
templatestringThe template sent.
invoice_idintThe invoice id.
Errors 4
not_found404No such invoice.
template_required422No template was given.
invalid_template422The template is not recognised, or it is switched off.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices/1231/notifications' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"template":"invoice-created"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/notifications`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ template: 'invoice-created' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/notifications');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['template' => 'invoice-created']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A switched-off template gives a 422; the list on screen does not mark which are on.
Api::Invoices()->SendInvoiceNotification([
'id' => $id,
'template' => 'invoice-created',
]);
```
#### Formalising an Invoice
post/api/v1/admin/invoices/{id}/formalize
`Invoices/FormalizeInvoice` admin once only
Turns an invoice into a formal one.
Body 1
notifyboolTells the client. It goes out when a formalisation file is there.
Response fields data
dataobjectThe invoice as it now stands. Same shape as the detail endpoint.
Errors 4
not_found404No such invoice.
already_formalized422The invoice is already formal.
blocked_by_gate422A hook refused it.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices/1231/formalize' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"notify":false}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/formalize`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ notify: false }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/formalize');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['notify' => false]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A second call gives a 422; in a batch script read the invoice's state first.
$inv = Api::Invoices()->GetInvoice(['id' => $id])['data'];
if (! $inv['formalized']) Api::Invoices()->FormalizeInvoice(['id' => $id]);
```
#### Sending a Reminder
post/api/v1/admin/invoices/{id}/remind
`Invoices/RemindInvoice` admin
Sends the client a reminder for an unpaid invoice.
Body —
——No body is needed, send an empty one. The invoice comes from the path, and the notification sent is `invoice-reminder`; there is no field to change it with.
Response fields data — 2
remindedboolWhether the send ran.
invoice_idintThe invoice id.
Errors 2
not_found404No such invoice.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices/1231/remind' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/remind`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/remind');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The call counts NO ATTEMPTS; it will remind the same invoice again and again.
Api::Invoices()->RemindInvoice(['id' => $id]);
```
### Pitfalls
> **A status change never travels alone**
>
> Marking an invoice paid **opens an income entry**. It also gives the invoice a paid number and sets the linked services moving. Refunding winds all of that back, unwinds the metered rows and can order a refund through the payment module. Do not try this on a real client's invoice.
> **Moving to the same status is an error**
>
> When the invoice already stands there, the call is **refused**. The one exception is changing the payment method on a paid invoice, where the status holds and only the method is written. A script that syncs statuses should read the current one first.
> **The client correction belongs to the invoice**
>
> This endpoint corrects the **frozen copy** on the invoice and leaves the live client record alone. A wrong address may need fixing in both places. Correct it here for the document already issued, and on the client for the ones to come. A correction here does not reach other invoices either.
> **Formalising happens once**
>
> Formalising an invoice that is already formal **gives an error**. In a batch script that stops the loop at the first one, so read each invoice's state first. A hook can refuse it as well, because on some installations the act has a counterpart in the books.
> **Reminders are not counted**
>
> The reminder endpoint **keeps no count** of how often it was called, and calling it twice sends the same client two mails. A script that walks the overdue invoices should keep on its own side which invoice was reminded and when. Otherwise every run warns everyone again.
### Related Articles
- [Managing Invoices](https://dev.wisecp.com/en/managing-invoices)
- [Invoice Items and Payments](https://dev.wisecp.com/en/invoice-items-and-payments)
- [Cash Records](https://dev.wisecp.com/en/cash-records)
## Invoice Items and Payments
https://dev.wisecp.com/en/invoice-items-and-payments
The four endpoints that edit and split invoice lines and hold the payment records.
### Overview
These four endpoints run the **money side** of an invoice. Two deal with its lines: editing them and moving some onto an invoice of their own. The other two deal with payment records.
The line endpoint works in **bulk**: one call adds, updates and removes. When it is done the totals are worked out again. The subtotal, the tax and the grand total are never written by hand.
A payment record moves the invoice status **one way only**. Clearing the balance turns it paid, while removing a payment does not turn it back.
### Reference
#### Writing the Lines
put/api/v1/admin/invoices/{id}/items
`Invoices/UpdateInvoiceItems` admin the totals are recomputed
Adds, updates and removes an invoice's lines in one call.
Body 3
itemsarrayThe lines to work on. One carrying an id gets updated, one without is added as new.
deleted_idsint[]The line ids to remove.
removed_discountsarrayThe discounts to take off. Each entry carries the discount type and the line it belongs to.
Line fields items[] — 10
item_idintThe id of an existing line. Left out, a new line is opened.
descriptionstringreqWhat the line is for.
quantityintreqHow many.
amountfloatreqThe unit amount.
discountfloatA discount on this line.
discount_typestringWhether the discount is an amount or a share.
tax_ratefloatA tax rate for this line. Left empty, the invoice's rate is used.
tax_exemptboolKeeps the line free of tax.
user_pidintThe service it covers.
oduedatestringThe end of the line's period.
Response fields data
dataobjectThe invoice as it now stands. Its totals arrive recomputed.
Errors 3
not_found404No such invoice.
item_required422No line would remain when the call is done.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/invoices/1212/items' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"items":[{"item_id":2811,"description":"Hosting","quantity":1,"amount":12.5}],"deleted_ids":[2812]}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/items`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
items: [
{ item_id: 2811, description: 'Hosting Plan', quantity: 1, amount: 12.5 },
{ description: 'Setup Fee', quantity: 1, amount: 5 },
],
deleted_ids: [2812],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/items');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'items' => [
['item_id' => 2811, 'description' => 'Hosting Plan', 'quantity' => 1, 'amount' => 12.5],
['description' => 'Setup Fee', 'quantity' => 1, 'amount' => 5],
],
'deleted_ids' => [2812],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A line you leave out is NOT removed; to remove one, put its id in the deleted list.
Api::Invoices()->UpdateInvoiceItems([
'id' => $id,
'items' => [['item_id' => 2811, 'description' => 'Hosting', 'quantity' => 1, 'amount' => 12.5]],
'deleted_ids' => [2812],
]);
```
#### Splitting the Lines
post/api/v1/admin/invoices/{id}/items/split
`Invoices/SplitInvoiceItems` admin opens a new invoice
Moves the lines you pick onto a new invoice.
Body 1
item_idsint[]reqThe lines to move. All have to belong to the source, and one line has to stay behind.
Response fields data — 4
source_invoice_idintThe source invoice id.
new_invoice_idintThe invoice opened.
new_invoice_numberstring | nullThe new invoice's number. Empty until a number is given.
moved_item_idsint[]The lines that moved.
Errors 6
not_found404No such invoice.
split_required422No line was picked.
no_items422The lines do not belong to this invoice.
split_one_left422No line would stay on the source.
split_failed422The new invoice could not be opened.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices/1228/items/split' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"item_ids":[2835]}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/items/split`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ item_ids: [2835] }),
});
const { data } = await res.json();
console.log(data.new_invoice_id);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/items/split');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['item_ids' => [2835]]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The new invoice opens UNPAID and the client is NOT told about it by itself.
$r = Api::Invoices()->SplitInvoiceItems(['id' => $id, 'item_ids' => $picked])['data'];
Api::Invoices()->SendInvoiceNotification([
'id' => $r['new_invoice_id'], 'template' => 'invoice-created',
]);
```
#### Recording a Payment
post/api/v1/admin/invoices/{id}/payments
`Invoices/AddInvoicePayment` admin clears the balance to paid
Adds a payment record to an invoice by hand.
Body 7
amountfloatreqThe amount paid. It has to be above zero.
payment_methodstringreqHow the money came in.
currency_idintThe payment currency. It gets converted when it differs from the invoice.
transaction_idstringThe transaction number. A second record with the same one is refused.
descriptionstringWhat the payment was.
paid_atstringThe date it was paid.
feesfloatThe fee taken.
Response fields data + meta — 1
dataobjectThe invoice as it now stands. Once the balance clears, the status turns to paid.
payment_idintThe id of the payment record opened. It comes back under meta.
Errors 5
not_found404No such invoice.
invalid_amount422The amount is zero or below.
method_required422No payment method was given.
payment_rejected422The invoice is already paid, the transaction number repeats, or the currency is not valid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices/1212/payments' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"amount":12.5,"payment_method":"Balance","transaction_id":"TXN-1042"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/payments`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
amount: 12.5,
payment_method: 'Balance',
currency_id: 840,
transaction_id: 'TXN-1042',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/payments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'amount' => 12.5,
'payment_method' => 'Balance',
'transaction_id' => 'TXN-1042',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The transaction number guards against DOUBLES; retrying after a network error is safe.
Api::Invoices()->AddInvoicePayment([
'id' => $id,
'amount' => 12.5,
'payment_method' => 'Balance',
'transaction_id' => $txn,
]);
```
#### Removing a Payment
delete/api/v1/admin/invoices/{id}/payments/{payment_id}
`Invoices/DeleteInvoicePayment` admin the status does not follow
Takes a payment record off an invoice.
Response fields data
dataobjectThe invoice as it now stands. What was paid and what remains are worked out again.
Errors 3
not_found404That payment is not on this invoice.
invalid_payment422The payment id is not valid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/invoices/1212/payments/31' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/${id}/payments/${paymentId}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/' . $id . '/payments/' . $paymentId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The invoice stays PAID: the balance reopens, and turning the status back is your job.
Api::Invoices()->DeleteInvoicePayment(['id' => $id, 'payment_id' => $pid]);
Api::Invoices()->UpdateInvoiceStatus(['id' => $id, 'status' => 'unpaid']);
```
### Pitfalls
> **Leaving a line out does not remove it**
>
> A line you do not send on the write call **stays put**. Removing it means putting its id in the deleted list. A script that sends the line set as it stands will not remove what was taken out. Compare the two lists and write the difference into the deleted list.
> **An invoice cannot be left with no lines**
>
> Both the write and the split call want **at least one line** left on the invoice when they finish. Trying to delete every line, or to split them all away, gives an error. To be rid of the invoice, remove or cancel the invoice itself rather than its lines.
> **Do not write the totals by hand**
>
> When the write call finishes, the subtotal, the tax and the grand total are **worked out again**. Trying to write a total through the invoice edit endpoint at the same time leaves a record pulled by two sources. Totals come from the lines, and changing them means changing the lines.
> **Removing a payment does not turn the status back**
>
> Clearing the balance turns an invoice paid by itself, yet removing the payment does not **walk that back**. What was paid and what remains are worked out again while the status stays paid. When undoing a payment entered by mistake, turn the status back to unpaid as a separate step.
> **A split brings a new debt into being**
>
> The split call opens a **new unpaid invoice** and tells the client nothing by itself. The client is left with another debt they have not heard of. After a split, take the new invoice id and send a notice. The source total drops as well, so both documents have changed.
### Related Articles
- [Managing Invoices](https://dev.wisecp.com/en/managing-invoices)
- [Invoice Status and Notices](https://dev.wisecp.com/en/invoice-status-and-notices)
- [Cash Records](https://dev.wisecp.com/en/cash-records)
## Cash Records
https://dev.wisecp.com/en/cash-records
The six endpoints that keep an installation's income and expense book.
### Overview
The cash book holds an installation's **income and expenses**. Two kinds of record sit in it together: the ones invoices open by themselves once paid, and the ones an operator enters by hand.
The **system mark** tells them apart. A record from an invoice is a reflection: it cannot be changed or removed, because its source is the invoice itself. Records entered by hand can be edited.
The summary gives **this month's** income, expenses and the difference between them. Amounts in other currencies are converted into the local one before adding.
### Reference
#### Listing the Records
get/api/v1/admin/invoices/cash
`Invoices/GetCashEntries` admin
Returns the income and expense records, filtered.
Query 10
pageintWhich page.
limitintRecords per page. A value out of range falls back to the default.
searchstringSearches the description, the staff member and the invoice number.
typestringLimits it to income or to expenses.
currency_idintFilters by currency.
staff_idintFilters by staff member.
amountstringFilters by amount.
amount_opstringWhich way the amount comparison runs.
descriptionstringSearches the description.
daterangestringFilters between two dates.
Response fields data[] — 13 + meta — 4
idintThe record id.
invoice_idintThe invoice it belongs to. Zero says the record was entered by hand.
typestringWhether it is income or an expense: `income`, `expense`.
amountfloatThe amount.
currency_idintThe currency it is in.
staff_idintThe staff member who entered it.
payment_methodstring | nullHow the money came in or went out.
descriptionstringWhat the record is for.
created_atstring | nullThe record date.
is_systemboolWhether it came from an invoice. When true the record cannot be changed.
invoice_numberstring | nullThe number of the invoice it belongs to.
staff_namestring | nullThe staff member's name.
clientobject | nullThe client on that invoice. It comes back in the list alone.
totalintHow many match the filter. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/cash?type=expense' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/invoices/cash');
url.searchParams.set('type', 'expense');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/cash?' . http_build_query(['type' => 'expense']));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list carries records FROM INVOICES too; filter on the system mark for hand-entered ones.
$manual = array_filter(
Api::Invoices()->GetCashEntries()['data'],
fn ($e) => ! $e['is_system'],
);
```
#### Adding a Record
post/api/v1/admin/invoices/cash
`Invoices/CreateCashEntry` admin
Puts an income or expense record into the book by hand.
Body 7
typestringreqWhether it is income or an expense: `income`, `expense`.
currency_idintreqThe currency of the amount.
amountfloatreqThe amount. It has to be above zero.
descriptionstringWhat the record is for.
payment_methodstringHow the money moved. A method that is switched off ends up empty.
staff_idintThe staff member entering it. Left out, the key's owner is written.
created_atstringThe record date. Left out, the moment of the call is used.
Response fields 201 — data — 13
dataobjectThe record opened. Same shape as a list item.
Errors 5
invalid_type422The type is neither income nor expense.
currency_required422No currency was given.
invalid_amount422The amount is zero or below.
create_failed422The record could not be opened.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices/cash' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"expense","currency_id":840,"amount":49.9,"description":"Sunucu gideri"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/invoices/cash', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'expense',
currency_id: 840,
amount: 49.9,
description: 'Server cost',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/cash');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'type' => 'expense',
'currency_id' => 840,
'amount' => 49.9,
'description' => 'Server cost',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A hand-entered record IS NOT TIED to an invoice; those only come from the payment flow.
Api::Invoices()->CreateCashEntry([
'type' => 'expense',
'currency_id' => 840,
'amount' => 49.9,
]);
```
#### Reading the Cash Summary
get/api/v1/admin/invoices/cash/summary
`Invoices/GetCashSummary` admin
Returns this month's income, expenses and balance.
Response fields data — 4
currency_idintThe currency the totals are in.
incomefloatThis month's income.
expensefloatThis month's expenses.
balancefloatThe expenses taken from the income.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/cash/summary' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/invoices/cash/summary', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/cash/summary');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The summary is ALWAYS this month; for another period pull the list by date and add it up.
$sum = Api::Invoices()->GetCashSummary()['data'];
```
#### Reading One Record
get/api/v1/admin/invoices/cash/{cash_id}
`Invoices/GetCashEntry` admin
Returns a single cash record.
Response fields data — 13
idintThe record id.
invoice_idintThe invoice it belongs to. Zero says the record was entered by hand.
typestringWhether it is income or an expense: `income`, `expense`.
amountfloatThe amount.
currency_idintThe currency it is in.
staff_idintThe staff member who entered it.
payment_methodstring | nullHow the money came in or went out.
descriptionstringWhat the record is for.
created_atstring | nullThe record date.
is_systemboolWhether it came from an invoice. When true the record cannot be changed.
invoice_numberstring | nullThe number of the invoice it belongs to.
staff_namestring | nullThe staff member's name.
clientobject | nullThe client on that invoice. It comes back in the list alone.
Errors 2
not_found404No such cash record.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/cash/51' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/cash/${cashId}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/cash/' . $cashId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The client details DO NOT arrive here; that field is filled by the list join alone.
$entry = Api::Invoices()->GetCashEntry(['cash_id' => $cashId])['data'];
```
#### Updating a Record
patch/api/v1/admin/invoices/cash/{cash_id}
`Invoices/UpdateCashEntry` admin invoice records are locked
Changes a cash record entered by hand.
Body 7
typestringWhether it is income or an expense.
currency_idintThe currency of the amount.
amountfloatThe amount.
descriptionstringWhat the record is for.
payment_methodstringHow the money moved.
staff_idintThe staff member who entered it.
created_atstringThe record date.
Response fields data — 13
dataobjectThe record as it now stands. Same shape as a list item.
Errors 6
not_found404No such cash record.
system_record422A record tied to an invoice cannot be touched.
invalid_type422The type is neither income nor expense.
currency_required422No currency was given.
invalid_amount422The amount is zero or below.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/invoices/cash/51' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"amount":59.9,"description":"Sunucu gideri (guncellendi)"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/cash/${cashId}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ amount: 59.9, description: 'Server cost (updated)' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/cash/' . $cashId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['amount' => 59.9]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A record marked as system gives a 422; in a bulk fix, filter on that field first.
$entry = Api::Invoices()->GetCashEntry(['cash_id' => $cashId])['data'];
if (! $entry['is_system'])
Api::Invoices()->UpdateCashEntry(['cash_id' => $cashId, 'amount' => 59.9]);
```
#### Removing a Record
delete/api/v1/admin/invoices/cash/{cash_id}
`Invoices/DeleteCashEntry` admin
Removes a cash record entered by hand.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the record removed.
Errors 4
not_found404No such cash record.
system_record422A record tied to an invoice cannot be touched.
delete_failed422The record could not be removed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/invoices/cash/52' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/cash/${cashId}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/cash/' . $cashId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A record from an invoice is removed on the INVOICE side; it cannot go from here.
Api::Invoices()->DeleteCashEntry(['cash_id' => $cashId]);
```
### Pitfalls
> **A record from an invoice cannot be changed**
>
> A cash record tied to an invoice is **read-only**: the update and delete calls are refused. That is deliberate, because the record reflects the invoice and cannot contradict it. To correct an amount, go back to the invoice and the cash record follows.
> **The list mixes the two kinds**
>
> The listing returns hand-entered records and invoice ones **together**, with no filter to separate them. To add up only the hand-entered expenses in a report, sift on the system mark yourself; otherwise invoice income lands in the sum.
> **The summary is always this month**
>
> The summary takes no period and always gives the **month you are in**. For last month or a quarter, pull the list by date and add it up yourself. You also have to handle the currency conversion, because the list does not arrive converted the way the summary does.
> **The detail carries no client**
>
> The client on the linked invoice arrives **in the list alone**, and reading one record leaves that field empty. The list performs a join and the detail does not. To get the client for a single record, read the invoice from its number.
> **A hand-entered record cannot be tied to an invoice**
>
> The create endpoint always opens a **standalone** record, and no invoice number ties one to an invoice. Records with that link come from the payment flow alone. So entering income by hand and also marking the same invoice paid shows the same money twice in the book.
### Related Articles
- [Recurring Expenses](https://dev.wisecp.com/en/recurring-expenses)
- [Managing Invoices](https://dev.wisecp.com/en/managing-invoices)
- [Invoice Status and Notices](https://dev.wisecp.com/en/invoice-status-and-notices)
## Recurring Expenses
https://dev.wisecp.com/en/recurring-expenses
The six endpoints that define the fixed outgoings repeating each month.
### Overview
Recurring expenses define the **payments that come round every month**: server rent, a licence fee, a subscription. What lives here is not an expense but a **rule** that brings expenses into being.
Each rule carries a **day and a time**. When the scheduled job reaches that moment the rule runs and writes that month's expense into the cash book. So the number of records here is not the number in the book.
The summary **looks forward**: it says how much fixed outgoing an installation has each month. To see what was actually paid, look at the cash book.
### Reference
#### Listing the Expenses
get/api/v1/admin/invoices/periodic
`Invoices/GetPeriodicExpenses` admin
Returns the expenses that repeat every month, filtered.
Query 8
pageintWhich page.
limitintRecords per page. A value out of range falls back to the default.
searchstringSearches the description.
currency_idintFilters by currency.
amountstringFilters by amount.
amount_opstringWhich way the amount comparison runs.
descriptionstringSearches the description.
daterangestringFilters between two dates.
Response fields data[] — 9 + meta — 4
idintThe record id.
amountfloatThe amount charged each month.
currency_idintThe currency it is in.
descriptionstringWhat the expense is.
dayintWhich day of the month it runs.
hourintThe hour it runs.
minuteintThe minute it runs.
timestringThe hour and minute joined together.
created_atstring | nullWhen the record was opened.
totalintHow many match the filter. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/periodic' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/invoices/periodic', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/periodic');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// These are RULES rather than records: each one brings a cash expense into being monthly.
$rules = Api::Invoices()->GetPeriodicExpenses()['data'];
```
#### Adding an Expense
post/api/v1/admin/invoices/periodic
`Invoices/CreatePeriodicExpense` admin a day and a time are needed
Defines an expense to be charged every month by itself.
Body 5
currency_idintreqThe currency of the amount.
amountfloatreqThe amount charged each month. It has to be above zero.
dayintreqWhich day of the month it runs. Between one and thirty-one.
timestringreqThe time it runs. Given as an hour and a minute, then split into both.
descriptionstringWhat the expense is.
Response fields 201 — data — 9
dataobjectThe expense opened. Same shape as a list item.
Errors 6
currency_required422No currency was given.
invalid_amount422The amount is zero or below.
invalid_day422The day is out of range.
invalid_time422The time is not in the expected form.
create_failed422The record could not be opened.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/invoices/periodic' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"currency_id":840,"amount":49.9,"day":1,"time":"09:00","description":"Aylik sunucu gideri"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/invoices/periodic', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
currency_id: 840,
amount: 49.9,
day: 1,
time: '09:00',
description: 'Monthly server cost',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/periodic');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'currency_id' => 840,
'amount' => 49.9,
'day' => 1,
'time' => '09:00',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Picking the thirty-first can leave the record unprocessed in the SHORT months.
Api::Invoices()->CreatePeriodicExpense([
'currency_id' => 840,
'amount' => 49.9,
'day' => 1,
'time' => '09:00',
]);
```
#### Reading the Summary
get/api/v1/admin/invoices/periodic/summary
`Invoices/GetPeriodicSummary` admin
Returns the total of the fixed monthly outgoings.
Response fields data — 3
currency_idintThe currency the total is in.
totalfloatThe monthly total. Other currencies are converted before adding.
countintHow many records went into it.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/periodic/summary' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/invoices/periodic/summary', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/periodic/summary');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This total looks FORWARD: it says what will be paid each month, not what was.
$plan = Api::Invoices()->GetPeriodicSummary()['data'];
```
#### Reading One Expense
get/api/v1/admin/invoices/periodic/{periodic_id}
`Invoices/GetPeriodicExpense` admin
Returns a single recurring expense.
Response fields data — 9
idintThe record id.
amountfloatThe amount charged each month.
currency_idintThe currency it is in.
descriptionstringWhat the expense is.
dayintWhich day of the month it runs.
hourintThe hour it runs.
minuteintThe minute it runs.
timestringThe hour and minute joined together.
created_atstring | nullWhen the record was opened.
Errors 2
not_found404No such recurring expense.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/invoices/periodic/8' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/periodic/${periodicId}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/periodic/' . $periodicId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The record does NOT carry when it last ran; read that from the cash book instead.
$rule = Api::Invoices()->GetPeriodicExpense(['periodic_id' => $id])['data'];
```
#### Updating an Expense
patch/api/v1/admin/invoices/periodic/{periodic_id}
`Invoices/UpdatePeriodicExpense` admin
Changes a recurring expense's amount or its timing.
Body 5
currency_idintThe currency of the amount.
amountfloatThe amount charged each month. It has to be above zero.
dayintWhich day of the month it runs. Between one and thirty-one.
timestringThe time it runs. An hour and a minute on the twenty-four hour clock.
descriptionstringWhat the expense is.
Response fields data — 9
dataobjectThe expense as it now stands. Same shape as a list item.
Errors 6
not_found404No such recurring expense.
currency_required422No currency was given.
invalid_amount422The amount is zero or below.
invalid_day422The day is out of range.
invalid_time422The time is not in the expected form.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/invoices/periodic/8' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"amount":59.9,"day":5,"time":"10:30"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/periodic/${periodicId}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ amount: 59.9, day: 5, time: '10:30' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/periodic/' . $periodicId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['amount' => 59.9, 'day' => 5]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The change does NOT reach back: what already ran this month keeps the old amount.
Api::Invoices()->UpdatePeriodicExpense(['periodic_id' => $id, 'amount' => 59.9]);
```
#### Removing an Expense
delete/api/v1/admin/invoices/periodic/{periodic_id}
`Invoices/DeletePeriodicExpense` admin
Removes a recurring expense.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the record removed.
Errors 3
not_found404No such recurring expense.
delete_failed422The record could not be removed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/invoices/periodic/8' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/invoices/periodic/${periodicId}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/invoices/periodic/' . $periodicId);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A delete leaves PAST cash records alone; it only stops the rule running again.
Api::Invoices()->DeletePeriodicExpense(['periodic_id' => $id]);
```
### Pitfalls
> **A late day can be skipped in the short months**
>
> The thirty-first is **not in every month**, and neither are the thirtieth and the twenty-ninth in some. A rule set to such a day can go unprocessed in those months and the expense never reaches the book. For an outgoing that has to run monthly, pick an early day.
> **Changing a rule does not reach back**
>
> Changing the amount or the day touches **only what comes after**. An expense already processed this month stays in the book at the old amount, and the new one shows next month. To correct the past, update the record in the cash book as a separate step.
> **A delete does not remove past expenses**
>
> Deleting a rule only stops it **running again**; the expense records it made up to that day stay in the book. That is the right behaviour, because those payments really happened. Clearing the past means removing those cash records as a separate step.
> **The record does not carry when it last ran**
>
> A recurring expense record does not say **when it last ran**. Telling whether a rule ran this month means looking in the cash book for a record matching its description. Weigh that when writing a check: the list here gives no run history on its own.
> **The summary looks forward and the book looks back**
>
> The summary here says **what will be paid** each month, while the cash summary says what was paid this month. The two do not match and are not meant to: a rule running on the twentieth is not in the book on the tenth. Keep them on separate lines in a report.
### Related Articles
- [Cash Records](https://dev.wisecp.com/en/cash-records)
- [Managing Invoices](https://dev.wisecp.com/en/managing-invoices)
- [Adding a Scheduled Job](https://dev.wisecp.com/en/adding-a-scheduled-task)
# API / Admin API / Knowledge Base
## Help Articles
https://dev.wisecp.com/en/help-articles
The five endpoints that write, read, update and remove help articles.
### Overview
A help article lives in two layers. The **structural data** holds the category, the state, who sees it and the order. The **content per language** holds the title, slug, body, tags and the search engine fields.
A title is required in every live language. The slug is optional and comes from the title when left empty, and it has to be unique **per language**.
The update is named as a partial change and behaves as a full write. The translation set is saved again for every language. Read the current state before changing anything.
### Reference
#### Listing the Articles
get/api/v1/admin/knowledgebase/articles
`Knowledgebase/GetKnowledgebaseArticles` admin
Returns the help articles with their read and vote counts.
Query 3
searchstringSearches the id, the title and the tags.
pageintWhich page.
limitintRecords per page. 100 at the most.
Response fields data[] — 10 + meta — 3
idintThe article id.
titlestringThe title. In the panel's current language.
routestringThe address slug.
categorystringThe category name.
statusstringPublished or a draft.
privateboolWhether only signed-in clients see it.
viewsintHow often it was read.
usefulintThe helpful votes.
uselessintThe unhelpful votes.
created_atstringWhen it was written.
totalintHow many articles there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/knowledgebase/articles?search=password' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/knowledgebase/articles', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const poor = data.filter((a) => a.useless > a.useful);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/articles');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The title comes in ONE language; comparing translations wants the detail endpoint.
$rows = Api::Knowledgebase()->GetKnowledgebaseArticles()['data'];
$weak = array_filter($rows, fn ($a) => $a['useless'] > $a['useful']);
```
#### Writing an Article
post/api/v1/admin/knowledgebase/articles
`Knowledgebase/CreateKnowledgebaseArticle` admin every language needed
Opens a new help article.
Body 6
translationsobjectreq translations.The content per language. A title is needed in every live language.
titlestringThe article title. It is needed in every live language.
routestringThe address slug. Left empty it comes from the title.
contentstringThe article body. It takes markup.
tagsstringThe tags.
seo_titlestringThe search engine title.
seo_keywordsstringThe search engine keywords.
seo_descriptionstringThe search engine description.
category_idintThe category it sits in. Zero means none.
statusstringPublished or a draft.
privateboolWhether only signed-in clients see it.
sidebarboolWhether the side column shows.
rankintWhere it sits in the listing.
Response fields 201 — data — 11
dataobjectThe article made. Same shape as the read endpoint, and the new id comes under meta as well.
Errors 4
title_required422The title is missing in one of the live languages.
route_in_use422The slug is taken by another article in that language.
vetoed422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/knowledgebase/articles' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"category_id":3,"translations":{"en":{"title":"How to reset your password","content":"Open the account page.
"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/knowledgebase/articles', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
category_id: 3,
status: 'published',
translations: {
en: { title: 'How to reset your password', route: 'reset-password', content: html },
},
}),
});
const { data, meta } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/articles');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'category_id' => 3,
'translations' => ['en' => ['title' => $title, 'content' => $html]],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// It wants a title in EVERY live language; a missing one turns the whole call down and nothing is saved.
$langs = array_column(Api::Reference()->GetLanguages()['data'], 'code');
foreach ($langs as $l) $t[$l] = ['title' => $titles[$l] ?? $titles['en']];
Api::Knowledgebase()->CreateKnowledgebaseArticle(['translations' => $t]);
```
#### Reading an Article
get/api/v1/admin/knowledgebase/articles/{id}
`Knowledgebase/GetKnowledgebaseArticle` admin
Returns an article with all of its languages.
Response fields data — 11
idintThe article id.
category_idintThe category it sits in.
statusstringPublished or a draft.
privateboolWhether only signed-in clients see it.
sidebarboolWhether the side column shows.
rankintWhere it sits in the listing.
viewsintHow often it was read.
usefulintThe helpful votes.
uselessintThe unhelpful votes.
created_atstringWhen it was written.
translationsobject translations.The content per language.
titlestringThe article title. It is needed in every live language.
routestringThe address slug. Left empty it comes from the title.
contentstringThe article body. It takes markup.
tagsstringThe tags.
seo_titlestringThe search engine title.
seo_keywordsstringThe search engine keywords.
seo_descriptionstringThe search engine description.
Errors 2
not_found404No such article.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/knowledgebase/articles/12' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/articles/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const missing = langs.filter((l) => ! data.translations[l]?.content);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/articles/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Read here BEFORE updating: an update rewrites the WHOLE translation set.
$a = Api::Knowledgebase()->GetKnowledgebaseArticle(['id' => $id])['data'];
$a['translations']['en']['content'] = $newHtml;
```
#### Updating an Article
patch/api/v1/admin/knowledgebase/articles/{id}
`Knowledgebase/UpdateKnowledgebaseArticle` admin a full write
Rewrites the article in full.
Body 6
translationsobjectreq translations.The content per language. The set is rewritten and a language you leave out is lost.
titlestringThe article title. It is needed in every live language.
routestringThe address slug. Left empty it comes from the title.
contentstringThe article body. It takes markup.
tagsstringThe tags.
seo_titlestringThe search engine title.
seo_keywordsstringThe search engine keywords.
seo_descriptionstringThe search engine description.
category_idintThe category it sits in. Zero means none.
statusstringPublished or a draft.
privateboolWhether only signed-in clients see it.
sidebarboolWhether the side column shows.
rankintWhere it sits in the listing.
Response fields data — 11
dataobjectThe article as it now stands. Same shape as the read endpoint.
Errors 5
not_found404No such article.
title_required422The title is missing in one of the live languages.
route_in_use422The slug is taken by another article in that language.
vetoed422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/knowledgebase/articles/12' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"draft","translations":{"en":{"title":"How to reset your password","content":"Updated steps.
"}}}'
```
```javascript
const cur = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/articles/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());
cur.data.translations.en.content = html;
const res = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/articles/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(cur.data),
});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/articles/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($article),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// It is named PATCH and behaves as a FULL WRITE: the translations are saved again for every language.
$a = Api::Knowledgebase()->GetKnowledgebaseArticle(['id' => $id])['data'];
$a['translations']['en']['content'] = $newHtml;
Api::Knowledgebase()->UpdateKnowledgebaseArticle($a + ['id' => $id]);
```
#### Removing an Article
delete/api/v1/admin/knowledgebase/articles/{id}
`Knowledgebase/DeleteKnowledgebaseArticle` admin
Removes an article, every translation of it and its header image.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the article removed.
Errors 3
not_found404No such article.
vetoed422A hook refused the delete.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/knowledgebase/articles/12' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/articles/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/articles/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The slug goes as well: old links to that address land on a not-found page.
Api::Knowledgebase()->UpdateKnowledgebaseArticle(['id' => $id, 'status' => 'draft'] + $article);
// moving it to a draft rather than removing keeps the address
```
### Pitfalls
> **The update rewrites the translation set**
>
> The update body is the **whole article**. Sending one language alone leaves the others unsaved and they go. Take the full set from the read endpoint first, change it there, and send all of it back.
> **A missing language stops the save outright**
>
> A title is needed in every live language, and one missing gives `422` while **no language is saved**. Articles that exist carry no title in a language added later, so the first edit meets this error. Take the language list from the reference endpoint and build the body from it.
> **The slug is unique per language**
>
> Using one slug on two articles gives `route_in_use`. The check is **per language**, so a slug taken in English can be free in another. During a bulk import the clash appears in one language alone and stops the whole save.
> **A private article is member-only rather than hidden**
>
> The private field limits an article to **signed-in clients** and it still shows in the panel and in search. Move the state to a draft when you mean to take content out of sight entirely.
> **Removing breaks the old links**
>
> Removing an article takes the slug with it and outside links to that address land on a not-found page. Moving one that search engines know to a **draft** is often better. The content goes out of sight and the address stays.
### Related Articles
- [Help Categories](https://dev.wisecp.com/en/help-categories)
- [Reference Lists](https://dev.wisecp.com/en/reference-lists)
## Help Categories
https://dev.wisecp.com/en/help-categories
The five endpoints that open, read, update and remove help categories.
### Overview
Categories group the help articles and **build a tree**. Every category can hang from another, and the ones at the root carry a parent of zero.
They follow the same contract as the articles. A title is wanted in every live language and a slug is optional, unique per language. An update writes the whole record.
One thing differs: a category's search engine fields are kept while **indexing is on**. Fields filled in while it is off are never saved.
### Reference
#### Listing the Categories
get/api/v1/admin/knowledgebase/categories
`Knowledgebase/GetKnowledgebaseCategories` admin
Returns the help categories.
Query 3
searchstringSearches the title.
pageintWhich page.
limitintRecords per page. 100 at the most.
Response fields data[] — 5 + meta — 3
idintThe category id.
titlestringThe title. In the panel's current language.
routestringThe address slug.
statusstringWhether the category is on.
iconstringThe icon class.
totalintHow many categories there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/knowledgebase/categories' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/knowledgebase/categories', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const byId = Object.fromEntries(data.map((c) => [c.id, c.title]));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/categories');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The listing holds NO parent id: building the tree wants the detail of every category.
$rows = Api::Knowledgebase()->GetKnowledgebaseCategories()['data'];
foreach ($rows as $c)
$parent[$c['id']] = Api::Knowledgebase()->GetKnowledgebaseCategory(['cid' => $c['id']])['data']['parent_id'];
```
#### Opening a Category
post/api/v1/admin/knowledgebase/categories
`Knowledgebase/CreateKnowledgebaseCategory` admin every language needed
Opens a new help category.
Body 6
translationsobjectreq translations.The content per language. A title is needed in every live language.
titlestringThe category title. It is needed in every live language.
routestringThe address slug. Left empty it comes from the title.
sub_titlestringThe subtitle.
contentstringThe category description.
seo_titlestringThe search engine title. The search engine fields are kept while indexing is on.
seo_keywordsstringThe search engine keywords.
seo_descriptionstringThe search engine description.
parent_idintThe parent category. Zero means the root.
statusstringWhether the category is on.
rankintWhere it sits in the listing.
iconstringThe icon class.
seo_indexboolWhether the search engine fields are kept and indexed.
Response fields 201 — data — 7
dataobjectThe category made. Same shape as the read endpoint, and the new id comes under meta as well.
Errors 5
title_required422The title is missing in one of the live languages.
route_in_use422The slug is taken by another category in that language.
invalid_parent422A category cannot be its own parent.
vetoed422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/knowledgebase/categories' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"parent_id":0,"icon":"bi bi-book","translations":{"en":{"title":"Billing"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/knowledgebase/categories', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
parent_id: 0,
icon: 'bi bi-book',
seo_index: true,
translations: { en: { title: 'Billing', sub_title: 'Invoices and payments' } },
}),
});
const { data, meta } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/categories');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'parent_id' => 0, 'translations' => ['en' => ['title' => 'Billing']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The search engine fields are not kept while indexing is OFF: filling them in loses them.
Api::Knowledgebase()->CreateKnowledgebaseCategory([
'seo_index' => true,
'translations' => ['en' => ['title' => 'Billing', 'seo_title' => 'Billing help']],
]);
```
#### Reading a Category
get/api/v1/admin/knowledgebase/categories/{cid}
`Knowledgebase/GetKnowledgebaseCategory` admin
Returns a category with all of its languages.
Response fields data — 7
idintThe category id.
parent_idintThe parent category.
statusstringWhether the category is on.
rankintWhere it sits in the listing.
iconstringThe icon class.
seo_indexboolWhether search engine indexing is on.
translationsobject translations.The content per language.
titlestringThe category title. It is needed in every live language.
routestringThe address slug. Left empty it comes from the title.
sub_titlestringThe subtitle.
contentstringThe category description.
seo_titlestringThe search engine title. The search engine fields are kept while indexing is on.
seo_keywordsstringThe search engine keywords.
seo_descriptionstringThe search engine description.
Errors 2
not_found404No such category.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/knowledgebase/categories/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/categories/${cid}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/categories/' . $cid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The parent id comes HERE alone; call this for every category while building the tree.
$c = Api::Knowledgebase()->GetKnowledgebaseCategory(['cid' => $cid])['data'];
$isRoot = (int) $c['parent_id'] === 0;
```
#### Updating a Category
patch/api/v1/admin/knowledgebase/categories/{cid}
`Knowledgebase/UpdateKnowledgebaseCategory` admin a full write
Rewrites the category in full.
Body 6
translationsobjectreq translations.The content per language. The set is rewritten and a language you leave out is lost.
titlestringThe category title. It is needed in every live language.
routestringThe address slug. Left empty it comes from the title.
sub_titlestringThe subtitle.
contentstringThe category description.
seo_titlestringThe search engine title. The search engine fields are kept while indexing is on.
seo_keywordsstringThe search engine keywords.
seo_descriptionstringThe search engine description.
parent_idintThe parent category. Zero means the root.
statusstringWhether the category is on.
rankintWhere it sits in the listing.
iconstringThe icon class.
seo_indexboolWhether the search engine fields are kept and indexed.
Response fields data — 7
dataobjectThe category as it now stands. Same shape as the read endpoint.
Errors 6
not_found404No such category.
title_required422The title is missing in one of the live languages.
route_in_use422The slug is taken by another category in that language.
invalid_parent422A category cannot be its own parent.
vetoed422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/knowledgebase/categories/3' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"inactive","translations":{"en":{"title":"Billing"}}}'
```
```javascript
const cur = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/categories/${cid}`, {
headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());
const res = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/categories/${cid}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ...cur.data, rank: 2 }),
});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/categories/' . $cid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($category),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Closing a category DOES NOT remove its articles, and a client can no longer reach them through it.
$c = Api::Knowledgebase()->GetKnowledgebaseCategory(['cid' => $cid])['data'];
$c['status'] = 'inactive';
Api::Knowledgebase()->UpdateKnowledgebaseCategory($c + ['cid' => $cid]);
```
#### Removing a Category
delete/api/v1/admin/knowledgebase/categories/{cid}
`Knowledgebase/DeleteKnowledgebaseCategory` admin
Removes a category and every translation of it.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the category removed.
Errors 3
not_found404No such category.
vetoed422A hook refused the delete.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/knowledgebase/categories/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/knowledgebase/categories/${cid}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/knowledgebase/categories/' . $cid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The articles inside STAY and fall out of any category; move them elsewhere first.
$arts = Api::Knowledgebase()->GetKnowledgebaseArticles()['data'];
foreach ($arts as $a) { /* move the ones whose category is $cid */ }
Api::Knowledgebase()->DeleteKnowledgebaseCategory(['cid' => $cid]);
```
### Pitfalls
> **The listing is not enough to build the tree**
>
> The category listing **does not carry** the parent id; it gives the id, title, slug, state and icon alone. Building the tree wants each category read on its own, which on a large knowledge base means one call per category.
> **The update rewrites the translation set**
>
> As with the articles the update body is the **whole category**. Read the current state first and write over it, even to change the order alone. The languages and fields you leave out go empty.
> **The search engine fields are not saved while indexing is off**
>
> The search engine title, keywords and description stay only while **indexing is on**. Filling them in while it is off raises no error and the values are not saved, showing empty on the next read. Turn indexing on first.
> **Removing a category orphans its articles**
>
> Removing a category **does not remove** the articles inside. They fall out of any category, and a client cannot reach them from the category listing. The articles are still found by address and by search while the navigation breaks. Move them first.
> **The self-parent check looks one step deep**
>
> A category cannot be its own parent and that is checked. Longer loops carry **no such guard**: A under B with B under A passes. Take care not to build a cycle while rearranging the tree.
### Related Articles
- [Help Articles](https://dev.wisecp.com/en/help-articles)
- [Reference Lists](https://dev.wisecp.com/en/reference-lists)
# API / Admin API / Languages
## Language Packages
https://dev.wisecp.com/en/language-packages
The seven endpoints that see, copy, set up and remove the installed languages.
### Overview
A language lives in three places at once in WISECP: the **package file** (name, country, order, state), the **translation files** and the **language tables** holding product names, category titles and notification templates. This article manages the first and the whole.
A new language is never born empty; it is set up by **copying** one that is installed. The copy takes both the table rows and the file tree, which makes it heavy work.
One language is the **default** and that one is privileged: it cannot be closed, cannot be removed, and carries no language prefix in its addresses. Moving the default swaps those three behaviours between two languages.
### Reference
#### Listing the Installed Languages
get/api/v1/admin/languages
`Languages/GetLanguages` admin
Returns every language on the installation, the closed ones included.
Response fields data[] — 15 + meta — 2
keystringThe language key. This is what the addresses carry.
namestringThe language name in English.
show_namestringThe name shown to a client.
codestringThe language code.
code_hyphenstringThe language and country code together.
country_idintThe country id. Look to the reference endpoints for its name.
country_codestringThe country code.
statusboolWhether the language is on.
localboolWhether it is the default. One language on the installation carries this.
rtlboolWhether the language reads right to left.
rankintWhere it sits in the listing.
permalinkboolWhether permalinks are supported.
prefixstringWhere the address prefix stands. Off on the default language and on for the rest.
copiedstringThe name of the language it was copied from.
created_atstringWhen it was made.
countintHow many languages there are. It comes back under meta.
defaultstringThe default language key.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/languages' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/languages', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data, meta } = await res.json();
const live = data.filter((l) => l.status);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The closed ones come too; filter on status for the languages open to a client.
$r = Api::Languages()->GetLanguages();
$live = array_values(array_filter($r['data'], fn ($l) => $l['status']));
$def = $r['meta']['default'];
```
#### Listing What Can Be Downloaded
get/api/v1/admin/languages/available
`Languages/GetAvailableLanguages` admin a remote service
Returns the languages the WISECP translation service offers.
Response fields data[] + meta — 1
dataobject[]The language definitions the remote service returns. An empty list comes back when the service cannot be reached.
countintHow many came back. It comes back under meta.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/languages/available' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/languages/available', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data, meta } = await res.json();
if (meta.count === 0) showRetry();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/available');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// AN EMPTY LIST means one of two things: none exist or the remote service failed. They look alike.
$out = Api::Languages()->GetAvailableLanguages();
if (! $out['data']) $logger->warning('empty language list — check the service is reachable');
```
#### Reading One Language
get/api/v1/admin/languages/{key}
`Languages/GetLanguage` admin
Returns one language package.
Response fields data — 15
dataobjectThe language package. Same shape as an item in the listing.
Errors 2
language_not_found404No such language.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/languages/de' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${key}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The key is not the language CODE: a second country under one code takes the 'en-gb' form.
$pkg = Api::Languages()->GetLanguage(['key' => $key])['data'];
```
#### Making a Language by Copying
post/api/v1/admin/languages
`Languages/CreateLanguage` admin heavy work
Sets up a new language by copying one that is installed.
Body 6
copy_languagestringreqThe key of the language to copy. It has to be installed.
languagestringreqThe new language code. It needs letters; digits alone are turned down.
country_idintreqThe country id.
show_namestringreqThe name to show a client.
rankintWhere it sits in the listing.
rtlintSend 1 when it reads right to left.
Response fields 201 — data — 15
dataobjectThe language package set up. Read its key here; it can differ from the code you sent.
Errors 7
country_required422The country id is missing.
language_required422The language code is empty or all digits.
copy_language_invalid422The source language is not installed.
show_name_required422The display name is empty.
language_exists422That language and country pair is already installed.
copy_tables_failed500The language table rows could not be copied.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/languages' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"copy_language":"en","language":"de","country_id":276,"show_name":"Deutsch"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/languages', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
copy_language: 'en',
language: 'de',
country_id: 276,
show_name: 'Deutsch',
rank: 2,
}),
});
const { data } = await res.json();
const realKey = data.key; // 'de' olmayabilir
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'copy_language' => 'en',
'language' => 'de',
'country_id' => 276,
'show_name' => 'Deutsch',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// When the code you send IS already installed the key becomes 'code-country'; read it, do not assume.
$pkg = Api::Languages()->CreateLanguage([
'copy_language' => 'en', 'language' => 'en',
'country_id' => 826, 'show_name' => 'English (UK)',
])['data'];
$key = $pkg['key']; // 'en-gb'
```
#### Changing a Language's Settings
patch/api/v1/admin/languages/{key}
`Languages/UpdateLanguage` admin promoting is heavy
Changes the fields you send and can promote the language to default.
Body 5
show_namestringThe name shown to a client. It cannot be empty once sent.
rankintWhere it sits in the listing.
rtlintSend 1 when it reads right to left.
statusintWhether the language is on. It is ignored on the default language.
localintSend 1 to make this the default. It changes the address prefix of two languages at once.
Response fields data — 15
dataobjectThe language package as it now stands.
Errors 3
language_not_found404No such language.
show_name_required422The name you sent is empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/languages/de' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"show_name":"Deutsch","rank":2}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${key}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ show_name: 'Deutsch', rank: 2 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['show_name' => 'Deutsch', 'rank' => 2]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// On the DEFAULT language status is IGNORED: the answer is 200 while the language stays on.
$pkg = Api::Languages()->UpdateLanguage(['key' => $key, 'status' => 0])['data'];
if ($pkg['status']) $logger->info('the default language cannot be closed — nothing changed');
```
#### Turning a Language On and Off
put/api/v1/admin/languages/{key}/status
`Languages/SetLanguageStatus` admin
Opens a language to clients or closes it.
Body 1
statusintreqThe new state: 0 for off and 1 for on.
Response fields data — 2
keystringThe language key.
statusboolWhere it now stands.
Errors 5
language_not_found404No such language.
invalid_status422The state is neither 0 nor 1.
language_is_default422The default language cannot be closed.
no_change422The language already sits in the state you asked for.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/languages/de/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":1}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${key}/status`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: 1 }),
});
if (res.status === 422) { /* zaten aciksa buraya duser */ }
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key . '/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['status' => 1]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Writing the same state again is an ERROR; read the current one first during a bulk sync.
$pkg = Api::Languages()->GetLanguage(['key' => $key])['data'];
if ($pkg['status'] !== $wanted) Api::Languages()->SetLanguageStatus(['key' => $key, 'status' => (int) $wanted]);
```
#### Removing a Language
delete/api/v1/admin/languages/{key}
`Languages/DeleteLanguage` admin cannot be undone
Removes a language, its translations and every row belonging to it.
Response fields data — 2
deletedboolWhether the delete ran.
keystringThe key of the language removed.
Errors 4
language_not_found404No such language.
language_is_default422The default language cannot be removed.
remove_tables_failed500The language table rows could not be removed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/languages/de' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${key}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The product and category names IN THAT LANGUAGE go as well; export and keep them first.
$dump = Api::Languages()->ExportLanguageTranslations(['key' => $key])['data'];
file_put_contents("backup-$key.json", json_encode($dump));
Api::Languages()->DeleteLanguage(['key' => $key]);
```
### Pitfalls
> **The key made is not always the code you sent**
>
> When the language code you send is **already installed**, the new key takes the `code-country` form. Setting up a second English makes `en-gb` rather than `en`. Read the key from the answer, since every later call wants it.
> **Moving the default changes the addresses of two languages**
>
> Making a language the default **opens** the prefix on the old default and **closes** it on the new one. The public addresses of both languages change and the old links shift. The job also rewrites the settings file and forces the new language open. Do not run it unplanned on a live installation.
> **Two paths handle one state differently**
>
> The status endpoint turns down closing the default language with `422`. The settings endpoint **ignores** the same request quietly and answers `200` while the language stays open. A script mixing the two believes it closed something. Look at the state in the answer.
> **Writing the same state gives an error**
>
> The status endpoint answers `422` with `no_change` when the state you ask for is the one already there. The endpoint is not repeatable: a sync loop setting every language to open errors on the ones that are open. Read the current state before writing.
> **Removing takes more than the translations**
>
> Removing a language takes the translation files, the notification templates and the **language table rows**: the product names, category titles and page content in that language go with it. The only way back is a backup. Export the translations first.
> **An empty download list can mean a failure**
>
> The downloadable languages come from a remote service. When it cannot be reached the endpoint raises no error and returns an **empty list**. That makes "no languages" and "the service failed" look alike. Leave a way to retry before showing an empty result as "nothing to pick".
### Related Articles
- [Translation Strings](https://dev.wisecp.com/en/translation-strings)
- [Reference Lists](https://dev.wisecp.com/en/reference-lists)
## Translation Strings
https://dev.wisecp.com/en/translation-strings
The five endpoints that search, edit, remove and move translation strings.
### Overview
Translation strings live in **files** rather than the database. Every string has a **full key**, and that key also says which file holds it, as in `needs/button-save`.
The head of the key places a string in one of three sets: the client side, the admin panel and the system text left over. A search result comes back grouped under those three.
There are two ways to write, and they **differ on purpose**. The bulk edit is strict: seeing one key it does not know, it writes nothing. The import is forgiving: it skips what it does not know and writes the rest.
### Reference
#### Searching the Translations
get/api/v1/admin/languages/{key}/translations
`Languages/GetLanguageTranslations` admin 100 matches at most
Returns the translation strings carrying your text, in groups.
Query 1
searchstringreqThe text to look for. Three characters at the least, and the case matters.
Response fields data — 3 + meta — 3
clientobject clientThe matches on the client side.
totalintHow many matched in the group.
dataobjectA map pairing the full key with its value.
adminobjectThe matches in the admin panel.
systemobjectEvery other match. Error messages and shared text.
totalintHow many were gathered. It stops at a hundred, and the true total can be larger.
searchstringThe text you looked for.
truncatedboolWhether the hundred limit was reached.
Errors 3
language_not_found404No such language.
search_too_short422The search text is under three characters.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/languages/de/translations?search=Save' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL(`https://panel.example.com/api/v1/admin/languages/${key}/translations`);
url.searchParams.set('search', term);
const res = await fetch(url, { headers: { Authorization: `Bearer ${apiKey}` } });
const { data, meta } = await res.json();
if (meta.truncated) narrowTheSearch();
```
```php
$qs = http_build_query(['search' => $term]);
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key . '/translations?' . $qs);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The search is CASE SENSITIVE: 'save' and 'Save' do not give the same result.
$r = Api::Languages()->GetLanguageTranslations(['key' => $key], ['search' => 'Save']);
if ($r['meta']['truncated']) $logger->info('the result stopped at a hundred — narrow the search');
```
#### Editing Translations in Bulk
put/api/v1/admin/languages/{key}/translations
`Languages/UpdateLanguageTranslations` admin strict
Writes the values of the keys you give and leaves the rest alone.
Body 1
translationsobjectreqA map pairing the full key with its new value. One invalid key turns the whole request down.
Response fields data — 2
updatedintHow many keys were written.
languagestringThe language key.
Errors 4
language_not_found404No such language.
translations_required422The map is empty.
invalid_translation_key422A key points at a file that does not exist.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/languages/de/translations' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"translations":{"needs/button-save":"Speichern"}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${key}/translations`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
translations: {
'needs/button-save': 'Speichern',
'admin/services/page-list': 'Dienste',
},
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key . '/translations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'translations' => ['needs/button-save' => 'Speichern'],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// ONE invalid key turns the whole batch down; pick the import endpoint for bulk loading.
Api::Languages()->UpdateLanguageTranslations([
'key' => $key, 'translations' => ['needs/button-save' => 'Speichern'],
]);
```
#### Removing One Translation
delete/api/v1/admin/languages/{key}/translations
`Languages/DeleteLanguageTranslation` admin
Takes one translation string out of its file.
Body 1
keystringreqThe full translation key to remove. Do not mix it up with the language key in the address.
Response fields data — 3
deletedboolWhether the delete ran.
keystringThe translation key removed.
languagestringThe language key.
Errors 5
language_not_found404No such language.
key_required422No translation key was given.
invalid_translation_key422The translation key is not valid.
translation_file_not_found404The file the key points at does not exist.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/languages/de/translations' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"key":"needs/button-save"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${lang}/translations`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ key: 'needs/button-save' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $lang . '/translations');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['key' => 'needs/button-save']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A screen asking for a removed key prints EMPTY text; consider correcting rather than clearing it.
Api::Languages()->UpdateLanguageTranslations([
'key' => $lang, 'translations' => ['needs/button-save' => 'Speichern'],
]);
```
#### Exporting the Translations
get/api/v1/admin/languages/{key}/translations/export
`Languages/ExportLanguageTranslations` admin
Returns every translation string of a language as one flat map.
Response fields data + meta — 2
dataobjectA flat map pairing the full key with its value. It can go straight into the import endpoint.
countintHow many strings there are. It comes back under meta.
languagestringThe language key.
Errors 2
language_not_found404No such language.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/languages/de/translations/export' \
-H "Authorization: Bearer $API_KEY" > de.json
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${key}/translations/export`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data, meta } = await res.json();
console.log(`${meta.count} dize`);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key . '/translations/export');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The output is JSON and NOT a spreadsheet; the sheet format the panel offers is absent here.
$dump = Api::Languages()->ExportLanguageTranslations(['key' => $key])['data'];
file_put_contents("$key.json", json_encode($dump, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE));
```
#### Importing the Translations
post/api/v1/admin/languages/{key}/translations/import
`Languages/ImportLanguageTranslations` admin forgiving
Writes a translation map in bulk and skips the keys it does not know.
Body 1
translationsobjectreqA map pairing the full key with its value. The same shape the export produces.
Response fields data — 4
languagestringThe language key.
translationsintHow many keys you sent.
applied_filesintHow many files were written.
skipped_filesarrayThe keys skipped for want of a target file. This is the one sign of a quiet loss.
Errors 3
language_not_found404No such language.
translations_required422The map is empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/languages/de/translations/import' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"translations":{"needs/button-save":"Speichern"}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/languages/${key}/translations/import`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ translations: map }),
});
const { data } = await res.json();
if (data.skipped_files.length) reportSkipped(data.skipped_files);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/languages/' . $key . '/translations/import');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['translations' => $map]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A key it does not know is SKIPPED quietly; without counting them a missing translation goes unseen.
$out = Api::Languages()->ImportLanguageTranslations(['key' => $key, 'translations' => $map])['data'];
if ($out['skipped_files']) $logger->warning('skipped key', $out['skipped_files']);
```
### Pitfalls
> **Bulk edit and import meet one error differently**
>
> The bulk edit turns down the **whole batch** over one invalid key and writes nothing. The import skips that key quietly and writes the rest. Pick the first for careful editing and the second when loading an outside file.
> **Skipped keys show in the answer alone**
>
> The import lists what it skipped under `skipped_files` and says so nowhere else. A script that does not read the answer **never learns** it left part of the translations unwritten. Check that field on every run.
> **The search count is not a total**
>
> The search stops at the hundredth match and the `total` field gives what was **gathered** rather than what exists. A true `truncated` means there is more and how much stays unknown. Do not tie that number to a progress readout.
> **The search is case sensitive**
>
> The search text is matched as it stands: looking for `save` does not find the string `Save`. Search each spelling of a word on its own when replacing text across the installation.
> **Two different keys in one request**
>
> On the removal endpoint the address carries the **language key** and the body the **translation key**. Both go by the name `key`. Writing the language key into the body gives an invalid translation key error, which is not the language going missing.
> **The export does not give a spreadsheet**
>
> The spreadsheet output and the remote pull that the panel offers are **absent** here; the export returns a flat map and the import expects the same map. The two mirror each other, so a language exported from one installation loads into another as it stands.
### Related Articles
- [Language Packages](https://dev.wisecp.com/en/language-packages)
- [Reference Lists](https://dev.wisecp.com/en/reference-lists)
# API / Admin API / Modules
## Module Catalogue
https://dev.wisecp.com/en/module-catalogue
The five endpoints managing which modules exist and which ones run.
### Overview
Everywhere WISECP speaks to the outside world is a module: taking payment, registering domains, sending mail and messages, checking for fraud, and the product types. This article answers **which modules exist and which are running**.
Six groups exist and **they are not picked the same way**. The payment and product groups run several modules at once, while the mail, domain and message groups pick one. The fraud group turns each module on by itself.
That difference reaches the endpoints: the group-wide pick sits on one and the per-module switch on another. Which applies is decided by the group.
### Reference
#### Listing a Group's Modules
get/api/v1/admin/modules/{group}
`Modules/GetModules` admin
Returns the modules in a group along with the group's live picks.
Query 2
statusstringThe filter: `active` or `passive`.
searchstringSearches the module name and key.
Response fields data[] — 8 + meta — 6
keystringThe module key. This is what the addresses carry.
namestringThe module name.
descriptionstringA short description.
authorstringWho wrote it.
versionstringIts version.
activeboolWhether the installation uses it.
premiumboolWhether it is a paid module.
logostringThe full address of its logo.
countintHow many came back. It comes back under meta.
groupstringThe group key.
activestring[]The module keys the installation uses.
card_storage_modulestringThe payment module keeping cards. It comes on the payment group alone.
default_modulestringThe group's single pick. It comes on the mail, message and domain groups.
intl_modulestringThe module for messages abroad. It comes on the message group alone.
Errors 2
unknown_group404No such module group.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/modules/payment?status=active' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/modules/payment?status=active', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data, meta } = await res.json();
console.log(meta.active, meta.card_storage_module);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/payment?status=active');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Six groups exist: payment, registrars, mail, sms, fraud, product. Anything else gives 404.
foreach (['payment', 'registrars', 'mail', 'sms', 'fraud', 'product'] as $g)
$all[$g] = Api::Modules()->GetModules(['group' => $g])['meta']['active'];
```
#### Reading One Module
get/api/v1/admin/modules/{group}/{module}
`Modules/GetModule` admin
Returns a module's summary, its fields and what it can do.
Response fields data — 11
keystringThe module key. This is what the addresses carry.
namestringThe module name.
descriptionstringA short description.
authorstringWho wrote it.
versionstringIts version.
activeboolWhether the installation uses it.
premiumboolWhether it is a paid module.
logostringThe full address of its logo.
fieldsobject fieldsThe configuration fields. A password field has its value masked.
typestringThe field type.
namestringThe field label.
descriptionstringWhat the field is for.
valuestringIts current value.
optionsarrayThe choices on a field that has them.
checkedboolWhether a tick field is ticked.
capabilitiesobjectWhat the module supports: configuration fields, a connection test and keeping records.
payment_optionsobjectThe payment settings. They come on the payment group alone.
Errors 3
unknown_group404No such module group.
module_not_found404No such module.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/modules/payment/Stripe' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
if (data.capabilities.has_test_connection) showTestButton();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Build a form from the capabilities first: not every module has fields or a connection test.
$m = Api::Modules()->GetModule(['group' => $group, 'module' => $key])['data'];
if (! $m['capabilities']['has_config_fields']) $form = null;
```
#### Choosing a Group's Live Modules
put/api/v1/admin/modules/{group}/activation
`Modules/UpdateModuleActivation` admin the set is replaced
Writes which modules a group uses.
Body 8
modulesstring[]The keys to make live. On the payment and product groups; the list you send replaces what was there.
card_storage_modulestringThe payment module to keep cards. It joins the live list when it is not in it.
modulestringThe single pick. On the mail, domain and message groups; sending it empty clears the pick.
module_intlstringThe module for messages abroad.
intl_sms_serviceintThe channel for messages abroad.
sms_api_serviceintThe channel for the message interface.
turkey_sms_serviceintThe channel for messages inside Turkey. It applies when the installation's default language is Turkish.
Response fields data — 6
groupstringThe group key.
activestring[]The keys now live.
activatedstring[]What this call turned on.
deactivatedstring[]What this call turned off.
card_storage_modulestringThe payment module keeping cards.
modulestringThe single module picked.
Errors 5
unknown_group404No such module group.
module_not_found422One of the keys you sent is absent from that group.
activation_not_supported422The group does not take a group-wide pick.
blocked_by_gate422A hook refused to turn it on.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/modules/payment/activation' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"modules":["Free","Stripe"],"card_storage_module":"Stripe"}'
```
```javascript
const now = await fetch('https://panel.example.com/api/v1/admin/modules/payment', {
headers: { Authorization: `Bearer ${apiKey}` },
}).then((r) => r.json());
const res = await fetch('https://panel.example.com/api/v1/admin/modules/payment/activation', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ modules: [...now.meta.active, 'Stripe'] }),
});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/payment/activation');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['modules' => $keys]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list REPLACES the set: sending one key turns every other payment module off.
$live = Api::Modules()->GetModules(['group' => 'payment'])['meta']['active'];
Api::Modules()->UpdateModuleActivation([
'group' => 'payment', 'modules' => array_values(array_unique([...$live, 'Stripe'])),
]);
```
#### Turning One Module On and Off
put/api/v1/admin/modules/{group}/{module}/status
`Modules/SetModuleStatus` admin two groups
Turns a fraud or product module on and off one at a time.
Body 1
enabledintreqThe new state: 1 for on and 0 for off.
Response fields data — 11
dataobjectThe module read afresh. Same shape as the read endpoint.
Errors 6
unknown_group404No such module group.
enabled_required422The state field is missing.
not_supported422The group does not take a per-module switch.
module_error422The module refused to open. Usually a missing credential.
blocked_by_gate422A hook refused to turn it on.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/modules/fraud/MaxMind/status' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":1}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}/status`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: 1 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key . '/status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => 1]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// On a fraud module OPENING checks the credentials first; write the settings BEFORE that.
Api::Modules()->UpdateModuleSettings([
'group' => 'fraud', 'module' => $key, 'settings' => ['license_key' => $lic],
]);
Api::Modules()->SetModuleStatus(['group' => 'fraud', 'module' => $key, 'enabled' => 1]);
```
#### Removing a Module
delete/api/v1/admin/modules/{group}/{module}
`Modules/DeleteModule` admin it deletes files
Takes a module's files off the server.
Response fields data — 3
deletedboolWhether the delete ran.
groupstringThe group key.
keystringThe key of the module removed.
Errors 5
unknown_group404No such module group.
module_not_found404No such module.
blocked_by_gate422A hook refused the delete.
removal_failed422The files could not be removed. What is left needs clearing by hand.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/modules/payment/Stripe' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// It takes the settings and the credentials too; export the configuration and keep it first.
$cfg = Api::Modules()->GetModuleConfig(['group' => $group, 'module' => $key])['data'];
file_put_contents("$key.json", json_encode($cfg));
Api::Modules()->DeleteModule(['group' => $group, 'module' => $key]);
```
### Pitfalls
> **The group pick replaces the set**
>
> On the payment and product groups the list you send **replaces** the old one. Sending only the module you meant to add turns the others off, and clients stop seeing those payment methods. Read the list first and add to it.
> **Not every group opens from the same endpoint**
>
> The fraud modules **refuse** the group-pick endpoint and answer `activation_not_supported`; they open one at a time. The product group takes both roads. Sort the group first when writing a general management tool.
> **Picking a card keeper also turns it on**
>
> Naming the payment module that keeps cards **adds it to the live list** even when it was not there. Writing one field can open a payment method to clients. Read the live list in the answer and compare it against the set you expected.
> **Opening wants a credential**
>
> Opening a fraud module checks its credentials, and the call comes back with `module_error` when one is missing. Order matters during setup: **write the settings first** and open afterwards. The other way round fails, and the error comes from the module itself.
> **Removing takes the files off the server**
>
> The removal endpoint deletes the module's directory, and the settings and credentials go with it. When the files come away only in part the answer is `removal_failed` and a **half-removed directory** stays behind. Export the configuration before removing.
### Related Articles
- [Module Settings and Calls](https://dev.wisecp.com/en/module-settings-and-calls)
- [Reference Lists](https://dev.wisecp.com/en/reference-lists)
## Module Settings and Calls
https://dev.wisecp.com/en/module-settings-and-calls
The six endpoints covering one module's settings, test, methods and records.
### Overview
This article gathers the endpoints reaching **inside** a single module: reading and writing its settings, testing its connection, calling its own methods and seeing the records it keeps.
There are **two ways** to write settings and the difference matters. The settings endpoint follows the road the panel saves by, so the module's filters, validation and hooks all run. The configuration endpoint writes straight to the file.
Secrets never leave the server. Every password-like value comes back as a mask, and sending that same mask back means "leave this field alone".
### Reference
#### Reading the Raw Configuration
get/api/v1/admin/modules/{group}/{module}/config
`Modules/GetModuleConfig` admin
Returns a module's settings on disk as they stand.
Response fields data — 4
groupstringThe group key.
keystringThe module key.
statusboolWhether the module is on.
settingsobjectThe raw settings. A value under a secret-looking key comes back masked.
Errors 3
unknown_group404No such module group.
module_not_found404No such module.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/modules/mail/Mailjet/config' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}/config`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const masked = Object.entries(data.settings).filter(([, v]) => v === '**********');
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key . '/config');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Secrets come back MASKED: this output is NOT a backup, and the keys do not travel to another installation.
$cfg = Api::Modules()->GetModuleConfig(['group' => $group, 'module' => $key])['data'];
```
#### Writing the Raw Configuration
put/api/v1/admin/modules/{group}/{module}/config
`Modules/SaveModuleConfig` admin no validation
Merges the keys you send into the module's settings file.
Body 2
settingsobjectThe keys to merge in. Sending the mask back keeps the secret.
statusintThe module state. It is written on the product and fraud groups.
Response fields data — 4
dataobjectThe configuration read afresh. Same shape as the read endpoint.
Errors 4
unknown_group404No such module group.
module_not_found404No such module.
settings_required422Neither settings nor a state was sent.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/modules/mail/Mailjet/config' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"settings":{"from_name":"Support"}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}/config`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ settings: { from_name: 'Support' } }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key . '/config');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['settings' => ['from_name' => 'Support']]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This endpoint writes STRAIGHT to the file: the module's own validation and hooks DO NOT run.
// Pick the settings endpoint for daily work; this one is for recovery and migration.
Api::Modules()->SaveModuleConfig([
'group' => $group, 'module' => $key, 'settings' => ['from_name' => 'Support'],
]);
```
#### Saving the Settings
put/api/v1/admin/modules/{group}/{module}/settings
`Modules/UpdateModuleSettings` admin the module validates
Saves the settings through the module's own validation.
Body 7
settingsobjectThe module's configuration fields. Sending the mask back keeps the secret.
statusintThe module state. It applies on the payment and fraud groups.
commission_ratestringThe rate added for paying this way. Payment alone.
force_convert_tointThe currency number amounts turn into. Payment alone.
accepted_countriesarrayOpen to these countries alone. Payment alone.
unaccepted_countriesarrayClosed to these countries. Payment alone.
change_subscription_feeintWhether changing a subscription carries a fee. Payment alone.
Response fields data — 11
dataobjectThe module read afresh. Same shape as the read endpoint in the catalogue article.
Errors 4
unknown_group404No such module group.
module_not_found404No such module.
module_error422The module turned the settings down. The message comes from the module.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/modules/payment/Stripe/settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"settings":{"api_key":"sk_live_123"},"commission_rate":"2.5"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}/settings`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
settings: { api_key: 'sk_live_123' },
commission_rate: '2.5',
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key . '/settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['settings' => ['api_key' => $liveKey]]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The same road the panel saves by: the module's filters, validation and hooks DO run.
Api::Modules()->UpdateModuleSettings([
'group' => 'payment', 'module' => 'Stripe',
'settings' => ['api_key' => $liveKey], 'commission_rate' => '2.5',
]);
```
#### Testing the Connection
post/api/v1/admin/modules/{group}/{module}/test-connection
`Modules/TestModuleConnection` admin
Tries whether the module reaches the service behind it.
Body 1
settingsobjectThe settings to test with. A field you leave out comes from the saved configuration.
Response fields data — 3
groupstringThe group key.
keystringThe module key.
connectedboolWhether the connection was made.
Errors 4
unknown_group404No such module group.
module_not_found404No such module.
module_error422The test failed or the module offers none.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/modules/payment/Stripe/test-connection' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"settings":{"api_key":"sk_test_123"}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}/test-connection`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ settings: { api_key: candidate } }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key . '/test-connection');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['settings' => ['api_key' => $candidate]]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The test SAVES NOTHING: try a new key here first and write it with the settings endpoint when it passes.
$out = Api::Modules()->TestModuleConnection([
'group' => $group, 'module' => $key, 'settings' => ['api_key' => $candidate],
])['data'];
if ($out['connected']) Api::Modules()->UpdateModuleSettings([
'group' => $group, 'module' => $key, 'settings' => ['api_key' => $candidate],
]);
```
#### Running a Module Method
post/api/v1/admin/modules/{group}/{module}/methods/{method}
`Modules/RunModuleMethod` admin module specific
Calls a module's own panel method and returns what it gives.
Body —
*objectA free body belonging to the module. It is handed to the method as it stands.
Response fields data — 4
groupstringThe group key.
keystringThe module key.
methodstringThe method that ran.
resultstringWhat the method gave. Text or an object, and the markup the panel shows can come as well.
Errors 5
unknown_group404No such module group.
module_not_found404No such module.
method_required422The method name is empty.
method_error422The method was not found or returned an error.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/modules/product/SampleProduct/methods/crud-list' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"page":1}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/${group}/${key}/methods/${method}`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ page: 1 }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/' . $group . '/' . $key . '/methods/' . $method);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['page' => 1]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The result can be the PANEL's own output; its shape is the module's choice and not an API contract.
$out = Api::Modules()->RunModuleMethod([
'group' => $group, 'module' => $key, 'method' => $method, 'page' => 1,
])['data'];
$isMarkup = is_string($out['result']);
```
#### Reading the Fraud Records
get/api/v1/admin/modules/{group}/{module}/records
`Modules/GetFraudRecords` admin fraud alone
Returns what a fraud module flagged.
Query 3
pageintWhich page.
limitintRecords per page. 100 at the most.
searchstringSearches the records.
Response fields data[] — 7 + meta — 4
idintThe record id.
user_idintThe id of the client flagged.
user_full_namestringThe client's name.
user_company_namestringThe client's company.
messagestringThe reason the module wrote.
ipstringThe address the action came from.
created_atstringWhen the record was written.
countintHow many came back. It comes back under meta.
totalintHow many there are.
pageintThe page you are on.
limitintThe page size.
Errors 4
unknown_group404No such module group.
module_not_found404No such module.
not_supported422A group other than fraud, or a module keeping no records.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/modules/fraud/MaxMind/records?limit=50' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/modules/fraud/${key}/records`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data, meta } = await res.json();
const flagged = new Set(data.map((r) => r.user_id));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/modules/fraud/' . $key . '/records');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Keeping records is the module's choice: calling without seeing it in the capabilities gives 422.
$m = Api::Modules()->GetModule(['group' => 'fraud', 'module' => $key])['data'];
if ($m['capabilities']['has_records'])
$rows = Api::Modules()->GetFraudRecords(['group' => 'fraud', 'module' => $key])['data'];
```
### Pitfalls
> **The configuration endpoint skips the module's validation**
>
> The configuration endpoint writes settings **straight to the file**: the module's field filters, checks and save hooks never run. A value that is not valid goes in without an error and breaks on first real use. Pick the settings endpoint for daily work; the configuration one is for recovery and migration.
> **A masked secret is not a backup**
>
> The read endpoints return secret-looking values as a mask and never give the real one. Exporting a module's configuration and moving it to **another installation** carries no keys; the fields fill with masks there and the module fails. Move the secrets separately.
> **The test saves nothing**
>
> The connection test uses the settings you send for that call alone and **writes nothing** even when it passes. Testing a new key and forgetting to save means the configuration you saw working never existed. Write it with the settings endpoint afterwards.
> **The method result has no contract**
>
> The method endpoint calls the module's panel method and hands the result over as it stands. That result can be an object or the **markup the panel would show**. The module decides the shape and a version can change it, so do not build an integration that parses it.
> **Records exist on some fraud modules alone**
>
> The records endpoint answers `not_supported` outside the fraud group, and not every module in that group keeps records either. Look at the capabilities in the module detail before calling: when it is absent there the endpoint gives an **error** rather than an empty list.
### Related Articles
- [Module Catalogue](https://dev.wisecp.com/en/module-catalogue)
- [Reference Lists](https://dev.wisecp.com/en/reference-lists)
# API / Admin API / Notifications
## Managing Notification Templates
https://dev.wisecp.com/en/managing-notification-templates
The five endpoints that list, add, read, edit and remove notification templates.
### Overview
A notification template lives in two places. Its **behaviour** sits in the settings file: whether it is on, who it reaches and by which channel. Its **text** sits in separate files per language: the subject, the e-mail body and the message.
That split reaches the endpoints. The listing gives the behaviour alone, and seeing the text wants one template read on its own.
Templates fall into groups and a group brings its own rules: attaching the invoice document means something in the invoice group and is ignored in the others.
### Reference
#### Listing the Templates
get/api/v1/admin/notifications/templates
`Notifications/GetNotificationTemplates` admin
Returns every notification template under its group.
Response fields data[] — 3
groupstringThe group key.
namestringThe group's translated name.
templatesarray templates[]The templates in the group.
groupstringThe group it sits in.
keystringThe template key.
namestringIts translated name.
statusintWhether the template is on.
customboolWhether it was added by hand.
user_mailintWhether the client gets an e-mail.
admin_mailintWhether the staff get an e-mail.
user_smsintWhether the client gets a message.
admin_smsintWhether the staff get a message.
send_pdfintWhether the invoice document is attached. It comes empty outside the invoice group.
emailsstringExtra e-mail recipients.
phonesstringExtra phone recipients.
departmentsint[]The department ids tied to it.
variablesstringThe variables the template can use.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/notifications/templates' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/notifications/templates', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const flat = data.flatMap((g) => g.templates);
const off = flat.filter((t) => ! t.status);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/templates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list is GROUPED and carries NO content: the subject and body come on the detail endpoint.
$groups = Api::Notifications()->GetNotificationTemplates()['data'];
$flat = array_merge(...array_column($groups, 'templates'));
```
#### Adding a Template
post/api/v1/admin/notifications/templates
`Notifications/CreateNotificationTemplate` admin
Opens a new template under a group.
Body 2
groupstringreqThe group key.
keystringreqThe template key. A slash, dot or comma becomes a hyphen.
Response fields 201 — data — 14
dataobjectThe template made. Same shape as a template in the listing.
Errors 4
group_required422No group was given.
key_required422No key was given.
already_exists422A template with that group and key exists.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/notifications/templates' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"group":"account","key":"welcome-message"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/notifications/templates', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ group: 'account', key: 'welcome-message' }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/templates');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['group' => 'account', 'key' => 'welcome-message']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A new template is born EMPTY and the core never sends it by itself; you write the content and the trigger.
Api::Notifications()->CreateNotificationTemplate(['group' => 'account', 'key' => 'welcome-message']);
Api::Notifications()->UpdateNotificationTemplate([
'group' => 'account', 'key' => 'welcome-message',
'contents' => ['en' => ['subject' => 'Welcome', 'mail_content' => $html]],
]);
```
#### Reading a Template
get/api/v1/admin/notifications/templates/{group}/{key}
`Notifications/GetNotificationTemplate` admin
Returns a template's settings and its text in every language.
Response fields data — 15
groupstringThe group it sits in.
keystringThe template key.
namestringIts translated name.
statusintWhether the template is on.
customboolWhether it was added by hand.
user_mailintWhether the client gets an e-mail.
admin_mailintWhether the staff get an e-mail.
user_smsintWhether the client gets a message.
admin_smsintWhether the staff get a message.
send_pdfintWhether the invoice document is attached. It comes empty outside the invoice group.
emailsstringExtra e-mail recipients.
phonesstringExtra phone recipients.
departmentsint[]The department ids tied to it.
variablesstringThe variables the template can use.
contentsobject contents.The text per language.
subjectstringThe e-mail subject.
mail_contentstringThe e-mail body.
sms_contentstringThe message text.
Errors 2
not_found404No such template.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/notifications/templates/invoice/invoice-created' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/notifications/templates/${group}/${key}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const missing = langs.filter((l) => ! data.contents[l]?.subject);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/templates/' . $group . '/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The variables you may use are written here; another one written into a template goes out as TEXT.
$t = Api::Notifications()->GetNotificationTemplate(['group' => $g, 'key' => $k])['data'];
$allowed = $t['variables'];
```
#### Updating a Template
patch/api/v1/admin/notifications/templates/{group}/{key}
`Notifications/UpdateNotificationTemplate` admin
Writes the settings and text you send and leaves the rest alone.
Body 10
statusintWhether the template is on.
user_mailintWhether the client gets an e-mail.
admin_mailintWhether the staff get an e-mail.
user_smsintWhether the client gets a message.
admin_smsintWhether the staff get a message.
send_pdfintWhether the invoice document is attached. It is ignored outside the invoice group.
emailsstringExtra e-mail recipients.
phonesstringExtra phone recipients.
departmentsint[]The department ids. The list replaces rather than adds.
contentsobject contents.The text per language.
subjectstringThe e-mail subject.
mail_contentstringThe e-mail body.
sms_contentstringThe message text.
Response fields data — 15
dataobjectThe template as it now stands. Same shape as the read endpoint.
Errors 3
not_found404No such template.
config_write_failed422The settings file could not be written.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/notifications/templates/invoice/invoice-created' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":1,"user_mail":1,"departments":[1,2]}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/notifications/templates/${group}/${key}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
status: 1,
contents: { en: { subject: 'Your invoice', mail_content: html } },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/templates/' . $group . '/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['status' => 1]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The department list REPLACES what was there; read it first to add one.
$t = Api::Notifications()->GetNotificationTemplate(['group' => $g, 'key' => $k])['data'];
$t['departments'][] = $newDid;
Api::Notifications()->UpdateNotificationTemplate([
'group' => $g, 'key' => $k, 'departments' => $t['departments'],
]);
```
#### Removing a Template
delete/api/v1/admin/notifications/templates/{group}/{key}
`Notifications/DeleteNotificationTemplate` admin
Removes a template and its text in every language.
Response fields data — 3
deletedboolWhether the delete ran.
groupstringThe group key.
keystringThe key of the template removed.
Errors 2
not_found404No such template.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/notifications/templates/account/welcome-message' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/notifications/templates/${group}/${key}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/templates/' . $group . '/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Removing one of the CORE's own templates silences that event entirely; turning the state off is enough.
Api::Notifications()->UpdateNotificationTemplate(['group' => $g, 'key' => $k, 'status' => 0]);
```
### Pitfalls
> **The department list replaces what was there**
>
> The department list you send on an update **replaces** the one there. Sending only the department you meant to add takes the others out and they stop getting the notification. Read it first and merge the list.
> **An unknown variable goes out as text**
>
> The variables a template may use are written on its own record. Writing one that is not in that list **raises no error**; the notification goes out and the client sees the raw braces. Read the list allowed before writing the text.
> **A new template is never sent by itself**
>
> A template added by hand is a record and nothing more: **no event** in the core fires it. A module or a hook has to call it for anything to go out. Turning the template on produces no message on its own.
> **Two templates have their state tied to the sign-up setting**
>
> The on and off state of the e-mail and phone verification templates moves together with the **sign-up verification setting**. Closing the template closes the verification step in the sign-up flow as well. Changing it as though it were a display setting drops verification for new members.
> **The document attachment falls away quietly outside its group**
>
> The setting that attaches the invoice document works in the invoice group alone. Sending it on another group's template **raises no error**: the value is ignored and comes back empty on the read. That is not the save failing.
### Related Articles
- [Notification Layout](https://dev.wisecp.com/en/notification-layout)
- [Staff Departments](https://dev.wisecp.com/en/staff-departments)
- [Language Packages](https://dev.wisecp.com/en/language-packages)
## Notification Layout
https://dev.wisecp.com/en/notification-layout
The four endpoints managing the frame and logos every notification shares.
### Overview
Every notification goes out inside a shared **frame**: a heading at the top, the template's own body in the middle and a sign-off at the bottom. This article manages that frame and the logos inside it.
The frame is kept per language, since its words and its direction follow the language. The template engine is one choice for the **whole installation** and decides which syntax the variables use.
The write call checks the frame before saving it: an unknown variable or broken syntax is turned down. A broken frame never takes every notification down with it.
### Reference
#### Reading the Layout
get/api/v1/admin/notifications/settings
`Notifications/GetNotificationSettings` admin
Returns the frame every notification shares, along with the logos.
Response fields data — 3
enginestringThe template engine. It decides which syntax the variables use.
layoutobject layout.The frame pieces per language.
headerstringThe top piece.
contentstringThe middle piece the body lands in.
footerstringThe bottom piece.
logosobjectThe addresses of the top and bottom logo. Empty when none was uploaded.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/notifications/settings' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/notifications/settings', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const syntax = data.engine; // degiskenlerin yazimi buna bagli
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Changing the engine changes the variable syntax in EVERY template; read which one you are on first.
$cfg = Api::Notifications()->GetNotificationSettings()['data'];
$engine = $cfg['engine'];
```
#### Writing the Layout
put/api/v1/admin/notifications/settings
`Notifications/UpdateNotificationSettings` admin the syntax is checked
Changes the template engine and the frame pieces.
Body 2
enginestringThe template engine: none, Smarty or Twig.
layoutobject layout.The frame pieces per language. Every language sent is checked for its variables and syntax.
headerstringThe top piece.
contentstringThe middle piece the body lands in.
footerstringThe bottom piece.
Response fields data — 3
dataobjectThe layout as it now stands. Same shape as the read endpoint.
Errors 3
invalid_variable422An unknown variable was used.
invalid_syntax422The template syntax is wrong.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/notifications/settings' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"engine":"twig","layout":{"en":{"header":"","content":"{{ content }}","footer":""}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/notifications/settings', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
engine: 'twig',
layout: { en: { header, content: '{{ content }}', footer } },
}),
});
if (res.status === 422) showSyntaxError(await res.json());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['engine' => 'twig', 'layout' => $layout]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The check looks at the frame pieces ALONE: the templates' own bodies go unchecked when the engine changes.
Api::Notifications()->UpdateNotificationSettings([
'engine' => 'twig', 'layout' => $layout,
]);
```
#### Uploading a Logo
post/api/v1/admin/notifications/logos/{type}
`Notifications/UploadNotificationLogo` admin
Uploads the top or bottom logo of the notifications.
Body 1
filestringreqThe image. It goes as encoded content or as a remote address.
Response fields data — 2
typestringThe logo kind.
logostringThe full address of the logo uploaded.
Errors 5
invalid_type422The logo kind is neither top nor bottom.
file_required422No file was given.
file_invalid422The file could not be read.
upload_failed422The upload failed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/notifications/logos/header' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"file":"data:image/png;base64,iVBORw0KGgo..."}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/notifications/logos/${type}`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ file: dataUri }),
});
const { data } = await res.json();
```
```php
$uri = 'data:image/png;base64,' . base64_encode(file_get_contents($path));
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/logos/' . $type);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['file' => $uri]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A new logo REMOVES the old one and there is no way back; download and keep the current file first.
$cur = Api::Notifications()->GetNotificationSettings()['data']['logos']['header'] ?? '';
if ($cur) file_put_contents('logo-backup.png', file_get_contents($cur));
Api::Notifications()->UploadNotificationLogo(['type' => 'header', 'file' => $uri]);
```
#### Removing a Logo
delete/api/v1/admin/notifications/logos/{type}
`Notifications/DeleteNotificationLogo` admin
Removes the top or bottom logo.
Response fields data — 2
typestringThe logo kind.
deletedboolWhether the delete ran.
Errors 2
invalid_type422The logo kind is neither top nor bottom.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/notifications/logos/header' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/notifications/logos/${type}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/notifications/logos/' . $type);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Removing the logo DOES NOT remove the image tag in the layout: the frame can show a broken image.
Api::Notifications()->DeleteNotificationLogo(['type' => 'header']);
// clear the Merhaba
"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/pages', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'normal',
languages: {
en: { title: 'About Us', content: 'Hello
' },
},
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/pages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'type' => 'normal',
'languages' => ['en' => ['title' => 'About Us', 'content' => 'Hello
']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Leave the address out and it is built from the title; a clash in that language returns 422.
Api::Website()->CreatePage([
'type' => 'news',
'languages' => ['en' => ['title' => 'Maintenance notice']],
]);
```
#### Updating a Page
patch/api/v1/admin/website/pages/{id}
`Website/UpdatePage` admin
Changes the page fields and languages you send.
Body 14
languagesobjectreqThe content per language: title, route, body and search-engine fields. A title is needed in each language you send.
statusstringWhether the page is live. Live by default.
sidebarstringWhether the sidebar shows.
categoryintThe category the page belongs to.
seo_indexintLets search engines index the page.
imagesobjectImages to upload in the same call. A kind the type does not allow fails the call.
show_during_account_registrationintShows during sign-up. Contract type only.
show_during_purchaseintShows during checkout. Contract type only.
show_in_account_preferencesintShows in account preferences. Contract type only.
mandatory_account_preferencesintMakes acceptance required in account preferences. Contract type only.
visibilitystringWhether the page appears in listings. News and reference types only.
visible_to_userintShows in the client panel as well. News type only.
rankintWhere it sits in the listing. Reference type only.
websitestringThe reference's address. Reference type only.
Response fields data — 12
dataobjectThe page as it now stands. Same shape as the detail endpoint.
Errors 5
page_not_found404No such page.
title_required422A title was emptied in one language.
route_exists422That address is already in use in that language.
invalid_kind422The image kind does not suit this type.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/website/pages/5' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"inactive","languages":{"tr":{"title":"Sirketimiz"}}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/pages/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
status: 'inactive',
languages: { en: { title: 'About Our Company' } },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/pages/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'status' => 'inactive',
'languages' => ['en' => ['title' => 'About Our Company']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Only the language you send is written and the rest are KEPT; the type field is ignored.
Api::Website()->UpdatePage([
'id' => $id,
'languages' => ['en' => ['title' => 'About Our Company']],
]);
```
#### Deleting a Page
delete/api/v1/admin/website/pages/{id}
`Website/DeletePage` admin
Removes a page along with all its languages.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the page removed.
Errors 3
page_not_found404No such page.
blocked_by_gate422A hook refused the delete.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/pages/5' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/pages/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/pages/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// To take a page down, switch its STATUS off rather than delete: the address survives.
Api::Website()->UpdatePage(['id' => $id, 'status' => 'inactive']);
```
#### Uploading a Page Image
put/api/v1/admin/website/pages/{id}/images/{kind}
`Website/UploadPageImage` admin
Uploads a page image and puts it in place of the one before.
Path 2
idintThe page id.
kindstringThe image kind: `header-background`, `cover`, `mockup`. The cover suits news, blog posts and references, while the mock-up suits references alone.
Body 1
imagestringreqThe image to upload. Either an address or the data itself.
Response fields 201 — data — 2
kindstringThe kind uploaded.
urlstringThe image's public address.
Errors 3
page_not_found404No such page.
invalid_kind422The image kind does not suit this type.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/website/pages/5/images/header-background' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"image":"https://ornek.com/afis.jpg"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/pages/${id}/images/header-background`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ image: 'https://example.com/banner.jpg' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/pages/' . $id . '/images/header-background');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['image' => 'https://example.com/banner.jpg']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The cover and mock-up kinds also BUILD a thumbnail; the banner kind leaves one file.
Api::Website()->UploadPageImage([
'id' => $id, 'kind' => 'cover', 'image' => $data,
]);
```
#### Removing a Page Image
delete/api/v1/admin/website/pages/{id}/images/{kind}
`Website/DeletePageImage` admin
Removes a page image along with its thumbnail.
Path 2
idintThe page id.
kindstringThe image kind to remove: `header-background`, `cover`, `mockup`.
Response fields data — 3
deletedboolWhether the delete ran.
idintThe page id.
kindstringThe kind removed.
Errors 3
page_not_found404No such page.
invalid_kind422The image kind does not suit this type.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/pages/5/images/header-background' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/pages/${id}/images/header-background`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/pages/' . $id . '/images/header-background');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// To REPLACE an image there is no need to delete first; the upload takes its place.
Api::Website()->DeletePageImage(['id' => $id, 'kind' => 'cover']);
```
### Pitfalls
> **The type is chosen only at creation**
>
> The content type is part of what a record is, and the **update ignores it**. A record opened as a plain page cannot become a news item. You have to create it again with the right type and remove the old one. Getting the type wrong costs the address and the images as well.
> **The address is unique per language**
>
> The same address can sit side by side in **different languages**, yet two pages in one language cannot share it. The clash error names the language it happened in. Leave the address out and it is built from the title, so two news items with similar titles can collide unexpectedly.
> **The image kind depends on the page type**
>
> The banner suits every type. The **cover** is taken only on news, blog posts and references, and the **mock-up** only on references. A kind that does not suit comes back as a 422. This holds at creation too: an invalid kind in the body means the page is never created at all.
> **Type-bound fields sit silently on the others**
>
> The contract acceptance switches work on contracts alone. So do showing a news item in the client panel, and a reference's rank and address. Sent on another type they raise **no error** and do nothing. When behaviour does not follow, check the record's type first.
> **The update merges languages**
>
> On an update the languages you send are written and the ones you leave out are **kept**. Correcting one language does not mean carrying the others along. This differs from some other write endpoints, where the body counts as the whole definition and whatever is missing gets dropped.
### Related Articles
- [Website Categories](https://dev.wisecp.com/en/website-categories)
- [Website Menus](https://dev.wisecp.com/en/website-menus)
- [Homepage Slides](https://dev.wisecp.com/en/homepage-slides)
## Website Categories
https://dev.wisecp.com/en/website-categories
The seven endpoints that create, move and remove blog and reference categories.
### Overview
Categories exist for **two content types**: blog posts and references. Plain pages, contracts and news carry no category, so they never appear at these endpoints.
Categories form a **tree**. Each record can have a parent, and zero puts it at the root. That information comes back only at the detail endpoint, while the list gives records in a flat order.
The shape matches that of pages: content is kept **per language**, the type is fixed at creation, and the address is unique within each language. Images are simpler here, as a category has one header image.
### Reference
#### Listing the Categories
get/api/v1/admin/website/categories
`Website/GetCategories` admin
Returns the categories of the type you pick.
Query 4
typestringWhich type: `articles`, `references`. Blog categories by default.
searchstringSearches the titles.
pageintWhich page.
limitintRecords per page. A hundred at most.
Response fields data[] — 6 + meta — 5
idintThe category id.
typestringThe category type.
statusstringWhether the category is live.
titlestringIts title in the current language.
routestringIts address in the current language.
created_atstringWhen it was created.
totalintHow many there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
type stringThe type filtered on.
next_pageintThe next page. Zero means you are on the last one.
Errors 2
invalid_type422The category type is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/categories?type=articles' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/website/categories');
url.searchParams.set('type', 'articles');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/categories?' . http_build_query(['type' => 'articles']));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list carries NO PARENT: building the tree means reading each record on its own.
$cats = Api::Website()->GetCategories([], ['type' => 'articles'])['data'];
```
#### Reading One Category
get/api/v1/admin/website/categories/{id}
`Website/GetCategory` admin
Returns one category with all its languages.
Response fields data — 9
idintThe category id.
typestringThe category type: `articles`, `references`.
parentintThe parent category. Zero says it sits at the root.
rankintWhere it sits in the listing.
statusstringWhether the category is live.
optionsobjectThe category's options. The search-engine preference lives here.
created_atstring | nullWhen it was created.
languagesobjectTitle, address, description and search-engine fields per language.
imagestring | nullThe header image address.
Errors 2
category_not_found404No such category.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/categories/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/categories/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/categories/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The parent id comes back ONLY here; the tree is built from this field.
$cat = Api::Website()->GetCategory(['id' => $id])['data'];
$isRoot = $cat['parent'] === 0;
```
#### Creating a Category
post/api/v1/admin/website/categories
`Website/CreateCategory` admin the type is fixed
Opens a new category and writes its languages.
Body 7
typestringreqThe category type: `articles`, `references`. It cannot be changed later.
languagesobjectreqThe content per language: title, address, description and search-engine fields. A title is needed in each language you send.
statusstringWhether the category is live. Live by default.
rankintWhere it sits in the listing.
seo_indexintLets search engines index the category.
parentintThe parent category. Zero puts it at the root.
imagestringThe header image to upload in the same call. Either an address or the data itself.
Response fields 201 — data — 9
dataobjectThe category created. Same shape as the detail endpoint.
Errors 6
invalid_type422The category type is not recognised.
languages_required422No language was sent.
title_required422A title is empty in one language.
route_exists422That address is already in use in that language.
create_failed500The category could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/categories' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"articles","languages":{"tr":{"title":"Duyurular"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/categories', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
type: 'articles',
languages: { en: { title: 'Announcements' } },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/categories');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'type' => 'articles',
'languages' => ['en' => ['title' => 'Announcements']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// To nest a category give the PARENT id; zero puts it at the root.
Api::Website()->CreateCategory([
'type' => 'articles',
'parent' => $parentId,
'languages' => ['en' => ['title' => 'Release notes']],
]);
```
#### Updating a Category
patch/api/v1/admin/website/categories/{id}
`Website/UpdateCategory` admin
Changes the category fields and languages you send.
Body 6
languagesobjectreqThe content per language: title, address, description and search-engine fields. A title is needed in each language you send.
statusstringWhether the category is live. Live by default.
rankintWhere it sits in the listing.
seo_indexintLets search engines index the category.
parentintThe parent category. Zero puts it at the root.
imagestringThe header image to upload in the same call. Either an address or the data itself.
Response fields data — 9
dataobjectThe category as it now stands. Same shape as the detail endpoint.
Errors 4
category_not_found404No such category.
title_required422A title was emptied in one language.
route_exists422That address is already in use in that language.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/website/categories/3' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"inactive"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/categories/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: 'inactive' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/categories/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['status' => 'inactive']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Changing the parent MOVES the branch; whatever sits below comes along.
Api::Website()->UpdateCategory(['id' => $id, 'parent' => $newParent]);
```
#### Deleting a Category
delete/api/v1/admin/website/categories/{id}
`Website/DeleteCategory` admin sub-categories go too
Removes a category and every category beneath it.
Response fields data — 3
deletedboolWhether the delete ran.
idintThe id of the category removed.
removedarrayEvery id removed. The sub-categories appear in this list too.
Errors 2
category_not_found404No such category.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/categories/3' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/categories/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.removed); // [3, 7, 8]
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/categories/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Read the RETURNED list to see how many went; a call you read as one can take a branch.
$gone = Api::Website()->DeleteCategory(['id' => $id])['data']['removed'];
```
#### Uploading a Category Image
put/api/v1/admin/website/categories/{id}/image
`Website/UploadCategoryImage` admin
Uploads the category header image, in place of the one before.
Body 1
imagestringreqThe image to upload. A thumbnail is built as well.
Response fields 201 — data — 2
kindstringThe image kind. A category has one kind.
urlstringThe image's public address.
Errors 2
category_not_found404No such category.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/website/categories/3/image' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"image":"https://ornek.com/kapak.jpg"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/categories/${id}/image`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ image: 'https://example.com/cover.jpg' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/categories/' . $id . '/image');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['image' => 'https://example.com/cover.jpg']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A category has ONE image; unlike a page, there is no kind to choose.
Api::Website()->UploadCategoryImage(['id' => $id, 'image' => $data]);
```
#### Removing a Category Image
delete/api/v1/admin/website/categories/{id}/image
`Website/DeleteCategoryImage` admin
Removes the category header image.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe category id.
Errors 2
category_not_found404No such category.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/categories/3/image' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/categories/${id}/image`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/categories/' . $id . '/image');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// To REPLACE the image there is no need to delete first; the upload takes its place.
Api::Website()->DeleteCategoryImage(['id' => $id]);
```
### Pitfalls
> **A delete takes the whole branch**
>
> Deleting a category also deletes **every category beneath it**. What you read as removing one record can take a branch of the tree. The removed list in the response tells you what actually went, so read it before counting the call a success. Reading the detail first to see the parent links is the safest course.
> **The list does not show the tree**
>
> The listing endpoint **does not return** the parent field and gives records in a flat order. You cannot build a tree from it. When you need the hierarchy, read each record from the detail endpoint; there are rarely many categories, so this seldom hurts.
> **The type is fixed at creation**
>
> The category type is part of what a record is, and the **update ignores it**. A category opened for blog posts will not become one for references. Fixing a category opened under the wrong type means creating a new one and moving what sits inside.
> **The address is unique per language**
>
> The same address can sit side by side in **different languages**, yet two categories in one language cannot share it. Categories and pages draw on the same address space, so a category can clash with a page as well. Leave the address out and it is built from the title.
> **Changing the parent moves the branch**
>
> Changing the parent on an update moves **everything beneath it** along. Putting a category under one of its own descendants closes the tree on itself, and that branch drops out of the listings. Before moving one, make sure the target does not sit inside the branch you are moving.
### Related Articles
- [Website Pages](https://dev.wisecp.com/en/website-pages)
- [Website Menus](https://dev.wisecp.com/en/website-menus)
- [Customer Testimonials](https://dev.wisecp.com/en/customer-testimonials)
## Homepage Slides
https://dev.wisecp.com/en/homepage-slides
The eight endpoints for the homepage slider, its images and its videos.
### Overview
Slides feed the rotating area at the top of the homepage. Every slide has a **main image**, and that image is required; the texts, the link and the video are not.
Texts are kept **per language**: title, description and link live separately in each. Leave the text out in one language and the slide quietly shows there as image alone.
The image and the video have **endpoints of their own**. The image is always there, while the video is an optional layer, and removing it leaves the slide back on its image.
### Reference
#### Listing the Slides
get/api/v1/admin/website/slides
`Website/GetSlides` admin
Returns the slides in the homepage slider.
Query 3
searchstringSearches the titles.
pageintWhich page.
limitintRecords per page. A hundred at most.
Response fields data[] — 4 + meta — 4
idintThe slide id.
titlestringIts title in the current language.
linkstringIts link in the current language.
created_atstringWhen it was created.
totalintHow many slides there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/slides' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/slides', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list carries NO STATUS and NO RANK: read the detail to see which slide is live.
$slides = Api::Website()->GetSlides()['data'];
```
#### Reading One Slide
get/api/v1/admin/website/slides/{id}
`Website/GetSlide` admin
Returns one slide with its texts, image and video.
Response fields data — 7
idintThe slide id.
statusstringWhether the slide is live.
rankintWhere it sits in the slider.
created_atstring | nullWhen it was created.
languagesobjectThe title, description and link per language.
imagestring | nullThe main image address.
videoobject | nullThe video: its address and length. Empty when no video was set.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/slides/2' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The video field can come back EMPTY, so check it exists before reading.
$slide = Api::Website()->GetSlide(['id' => $id])['data'];
$clip = $slide['video']['url'] ?? null;
```
#### Creating a Slide
post/api/v1/admin/website/slides
`Website/CreateSlide` admin the image is required
Adds a new slide to the homepage slider.
Body 4
imagestringreqThe slide's main image. A slide cannot be created without one.
statusstringWhether the slide is live. Live by default.
rankintWhere it sits in the slider.
languagesobjectThe title, description and link per language. None of the texts is required.
Response fields 201 — data — 7
dataobjectThe slide created. Same shape as the detail endpoint.
Errors 3
image_required422No main image was sent.
create_failed500The slide could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/slides' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"image":"https://ornek.com/slayt.jpg","languages":{"tr":{"title":"Hos geldiniz"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/slides', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
image: 'https://example.com/slide.jpg',
languages: { en: { title: 'Welcome', link: 'https://example.com/' } },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'image' => 'https://example.com/slide.jpg',
'languages' => ['en' => ['title' => 'Welcome', 'link' => 'https://example.com/']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A slide is born LIVE and reaches the homepage at once; send it off while preparing.
Api::Website()->CreateSlide([
'image' => $data,
'status' => 'inactive',
]);
```
#### Updating a Slide
patch/api/v1/admin/website/slides/{id}
`Website/UpdateSlide` admin
Changes a slide's status, its place and its texts.
Body 4
statusstringWhether the slide is live.
rankintWhere it sits in the slider.
languagesobjectThe title, description and link per language.
imagestringReplaces the main image in the same call.
Response fields data — 7
dataobjectThe slide as it now stands. Same shape as the detail endpoint.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/website/slides/2' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"inactive","rank":1}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: 'inactive', rank: 1 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['status' => 'inactive', 'rank' => 1]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A rank does NOT push the others aside; give two slides the same number and the order blurs.
foreach ($order as $i => $slideId)
Api::Website()->UpdateSlide(['id' => $slideId, 'rank' => $i]);
```
#### Deleting a Slide
delete/api/v1/admin/website/slides/{id}
`Website/DeleteSlide` admin
Removes a slide along with its image and video.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the slide removed.
Errors 3
slide_not_found404No such slide.
delete_failed500The slide could not be removed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/slides/2' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Rather than delete a seasonal slide, switch its STATUS off: image and texts survive.
Api::Website()->UpdateSlide(['id' => $id, 'status' => 'inactive']);
```
#### Replacing the Slide Image
put/api/v1/admin/website/slides/{id}/image
`Website/SetSlideImage` admin
Puts a new main image in place of the slide's current one.
Body 1
imagestringreqThe new main image. A thumbnail is built as well.
Response fields 201 — data — 1
urlstringThe new image's public address.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/website/slides/2/image' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"image":"https://ornek.com/yeni.jpg"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}/image`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ image: 'https://example.com/new.jpg' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id . '/image');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['image' => 'https://example.com/new.jpg']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The update call does this too; the separate endpoint is for changing the image alone.
Api::Website()->SetSlideImage(['id' => $id, 'image' => $data]);
```
#### Setting a Slide Video
put/api/v1/admin/website/slides/{id}/video
`Website/SetSlideVideo` admin
Sets a background video on a slide.
Body 2
videostringreqThe video to upload. One format is accepted.
video_durationintHow long the video runs. The slider times its change by this.
Response fields 201 — data — 2
urlstringThe video's public address.
durationintThe length stored.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/website/slides/2/video' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"video":"https://ornek.com/klip.mp4","video_duration":12}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}/video`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
video: 'https://example.com/clip.mp4',
video_duration: 12,
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id . '/video');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'video' => 'https://example.com/clip.mp4',
'video_duration' => 12,
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// LEAVE THE LENGTH OUT and the slider change falls out of step; send the seconds with it.
Api::Website()->SetSlideVideo([
'id' => $id, 'video' => $data, 'video_duration' => 12,
]);
```
#### Removing a Slide Video
delete/api/v1/admin/website/slides/{id}/video
`Website/DeleteSlideVideo` admin
Removes a slide's video, leaving it back on its image.
Response fields data — 2
deletedboolWhether the call ran. It comes back true even with no video there.
idintThe slide id.
Errors 2
slide_not_found404No such slide.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/slides/2/video' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/slides/${id}/video`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/slides/' . $id . '/video');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// On a slide with no video the call passes QUIETLY; there is no need to check first.
Api::Website()->DeleteSlideVideo(['id' => $id]);
```
### Pitfalls
> **A new slide reaches the homepage at once**
>
> Leave the status field out and the slide is created **live**, so visitors begin seeing it that moment. The homepage is the most visible place on the site, so create a slide you are still preparing switched off and turn it on once the texts are done.
> **The list carries no status and no rank**
>
> The listing gives the id, title, link and date, and carries **no status and no rank field**. From the list alone you cannot tell which slide is live or in what order they appear. Read each slide from the detail endpoint for that; there are rarely many.
> **A rank does not push the others aside**
>
> Giving one slide a rank **does not shift** the others. Give two slides the same number and which comes first is left open, so the order can change from one page load to the next. When reordering, write increasing numbers across all of them.
> **Without the length the change falls out of step**
>
> The slider times its move to the next slide by the **length you give**. Upload a video without it and the change falls out of step: the clip is cut off, or a frozen frame stays once it ends. Send the length together with the video.
> **The image cannot be removed, only replaced**
>
> The video has an endpoint that removes it and the **image does not**. The main image is what makes a slide a slide: you can replace it, yet you cannot leave it empty. Letting go of the image means deleting the slide, and that takes its image and video with it.
### Related Articles
- [Website Pages](https://dev.wisecp.com/en/website-pages)
- [Customer Testimonials](https://dev.wisecp.com/en/customer-testimonials)
- [Website Menus](https://dev.wisecp.com/en/website-menus)
## Customer Testimonials
https://dev.wisecp.com/en/customer-testimonials
The seven endpoints that add, approve and remove the testimonials shown on the site.
### Overview
Testimonials are the reference texts shown on the site. Each carries a **status**: pending, approved or rejected. **Only the approved ones** appear on the site.
The text is kept **per language**, while the name, company and avatar are shared. What a visitor submits starts as pending and stays off the site until an administrator approves it.
These endpoints also let you **add a testimonial through the panel**: a reference that arrived on paper or by e-mail can be typed in and created approved outright.
### Reference
#### Listing the Testimonials
get/api/v1/admin/website/cfeedbacks
`Website/GetCfeedbacks` admin
Returns the customer testimonials on the site.
Query 3
searchstringSearches the name, company, e-mail and sending address.
pageintWhich page.
limitintRecords per page. A hundred at most.
Response fields data[] — 7 + meta — 4
idintThe testimonial id.
full_namestringThe name of whoever left it.
company_namestringThe person's company.
emailstringTheir e-mail address.
statusstringThe testimonial status: `pending`, `approved`, `rejected`.
rankintWhere it sits in the listing.
created_atstring | nullWhen it was submitted.
totalintHow many there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero means you are on the last one.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/cfeedbacks' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/cfeedbacks', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
const waiting = data.filter((f) => f.status === 'pending');
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/cfeedbacks');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// There is NO status filter; sift the list yourself to find what waits for a decision.
$all = Api::Website()->GetCfeedbacks()['data'];
$waiting = array_filter($all, fn ($f) => $f['status'] === 'pending');
```
#### Reading One Testimonial
get/api/v1/admin/website/cfeedbacks/{id}
`Website/GetCfeedback` admin
Returns one testimonial with its text and avatar.
Response fields data — 11
idintThe testimonial id.
full_namestringThe name of whoever left it.
company_namestringThe person's company.
emailstringTheir e-mail address.
statusstringThe testimonial status: `pending`, `approved`, `rejected`.
rankintWhere it sits in the listing.
unreadintThe unread mark. It is one on an approved testimonial.
ipstringThe address it came from.
created_atstring | nullWhen it was submitted.
languagesobjectThe testimonial text per language.
picturestring | nullThe avatar address.
Errors 2
cfeedback_not_found404No such testimonial.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/cfeedbacks/4' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/cfeedbacks/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/cfeedbacks/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The TEXT and the sending ADDRESS come back only here; the list carries neither.
$fb = Api::Website()->GetCfeedback(['id' => $id])['data'];
$en = $fb['languages']['en']['message'] ?? '';
```
#### Creating a Testimonial
post/api/v1/admin/website/cfeedbacks
`Website/CreateCfeedback` admin
Adds a customer testimonial through the panel.
Body 7
full_namestringreqThe name of whoever left it.
languagesobjectreqThe testimonial text per language. Text is needed in each language you send.
company_namestringThe person's company.
emailstringTheir e-mail address. It is not shown on the site.
statusstringThe testimonial status: `pending`, `approved`, `rejected`. Pending by default.
rankintWhere it sits in the listing.
imagestringThe avatar to upload in the same call.
Response fields 201 — data — 11
dataobjectThe testimonial created. Same shape as the detail endpoint.
Errors 6
full_name_required422The name is empty.
languages_required422No language was sent.
message_required422The text is empty in one language.
invalid_status422The status is not recognised.
create_failed500The testimonial could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/cfeedbacks' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"full_name":"Ayse Yilmaz","status":"approved","languages":{"tr":{"message":"Harika hizmet!"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/cfeedbacks', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
full_name: 'John Doe',
company_name: 'Example Inc.',
status: 'approved',
languages: { en: { message: 'Great service!' } },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/cfeedbacks');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'full_name' => 'John Doe',
'status' => 'approved',
'languages' => ['en' => ['message' => 'Great service!']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Leave the status out and it is born PENDING, unseen on the site; approve it as well.
Api::Website()->CreateCfeedback([
'full_name' => 'John Doe',
'status' => 'approved',
'languages' => ['en' => ['message' => 'Great service!']],
]);
```
#### Updating a Testimonial
patch/api/v1/admin/website/cfeedbacks/{id}
`Website/UpdateCfeedback` admin approval happens here
Changes a testimonial's status, text and details.
Body 7
full_namestringThe name of whoever left it. Left out, the current value is kept.
languagesobjectreqThe testimonial text per language. Text is needed in each language you send.
company_namestringThe person's company.
emailstringTheir e-mail address. It is not shown on the site.
statusstringThe testimonial status: `pending`, `approved`, `rejected`. Pending by default.
rankintWhere it sits in the listing.
imagestringThe avatar to upload in the same call.
Response fields data — 11
dataobjectThe testimonial as it now stands. Same shape as the detail endpoint.
Errors 5
cfeedback_not_found404No such testimonial.
full_name_required422The name was emptied.
message_required422The text was emptied in one language.
invalid_status422The status is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/website/cfeedbacks/4' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"status":"approved"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/cfeedbacks/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ status: 'approved' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/cfeedbacks/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['status' => 'approved']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Approval is a STATUS change rather than a switch; it is the one thing that publishes.
Api::Website()->UpdateCfeedback(['id' => $id, 'status' => 'approved']);
```
#### Deleting a Testimonial
delete/api/v1/admin/website/cfeedbacks/{id}
`Website/DeleteCfeedback` admin
Removes a testimonial.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the testimonial removed.
Errors 3
cfeedback_not_found404No such testimonial.
delete_failed500The testimonial could not be removed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/cfeedbacks/4' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/cfeedbacks/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/cfeedbacks/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Rather than delete, REJECT it: the record stays off the site while the words survive.
Api::Website()->UpdateCfeedback(['id' => $id, 'status' => 'rejected']);
```
#### Uploading the Avatar
put/api/v1/admin/website/cfeedbacks/{id}/picture
`Website/SetCfeedbackPicture` admin
Uploads the avatar shown beside a testimonial.
Body 1
imagestringreqThe avatar to upload. Either an address or the data itself.
Response fields 201 — data — 1
urlstringThe avatar's public address.
Errors 2
cfeedback_not_found404No such testimonial.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/website/cfeedbacks/4/picture' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"image":"https://ornek.com/avatar.jpg"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/cfeedbacks/${id}/picture`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ image: 'https://example.com/avatar.jpg' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/cfeedbacks/' . $id . '/picture');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['image' => 'https://example.com/avatar.jpg']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The avatar is NOT required; without one the theme puts its own placeholder there.
Api::Website()->SetCfeedbackPicture(['id' => $id, 'image' => $data]);
```
#### Removing the Avatar
delete/api/v1/admin/website/cfeedbacks/{id}/picture
`Website/DeleteCfeedbackPicture` admin
Removes a testimonial's avatar.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe testimonial id.
Errors 2
cfeedback_not_found404No such testimonial.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/cfeedbacks/4/picture' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/cfeedbacks/${id}/picture`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/cfeedbacks/' . $id . '/picture');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// To REPLACE the avatar there is no need to delete first; the upload takes its place.
Api::Website()->DeleteCfeedbackPicture(['id' => $id]);
```
### Pitfalls
> **A new testimonial is born pending**
>
> Leave the status field out and the testimonial is created **pending**, unseen on the site. For a reference typed in through the panel that is rarely what you want, so send the status approved at creation or update it straight after. For what a visitor submits, pending is the right start.
> **You cannot filter by status**
>
> The listing takes only a search term, a page and a page size, and offers **no status filter**. Finding what waits for approval means pulling the list and sifting it yourself. On an installation with many testimonials, plan for walking the pages and sifting each one.
> **The text is not in the list**
>
> The list gives the name, company, e-mail and status, yet **not the testimonial itself**. Deciding what to approve means reading each record from the detail endpoint. Weigh that when writing an approval flow: the list alone cannot carry the decision.
> **The e-mail and the address stay on the record**
>
> A testimonial record carries the sender's e-mail and the **address it came from**. Neither is shown on the site, yet both can be read from the detail endpoint. That is personal data, so take care not to carry these two fields along when writing an integration that moves testimonials elsewhere.
> **Reject rather than delete**
>
> A rejected testimonial stays off the site while the **record remains**: who wrote what, when, and what was decided all stay readable. Deleting takes all of that, and if the same person writes again you have no history to look at.
### Related Articles
- [Website Pages](https://dev.wisecp.com/en/website-pages)
- [Homepage Slides](https://dev.wisecp.com/en/homepage-slides)
- [The Contact Inbox](https://dev.wisecp.com/en/contact-inbox)
## Website Menus
https://dev.wisecp.com/en/website-menus
The seven endpoints that build, order and edit the trees of five menu groups.
### Overview
Website menus live in **five separate groups**: the header, the footer, the client panel, mobile and the sidebar. Each group is its own tree, and items do not move between groups.
An item either **points at a page** or carries a link written by hand. One pointing at a page follows that page when its address changes, while a hand-written link stays as it is.
The title, description, badge and mega-menu content are kept **per language**. The order and the nesting are written through an endpoint of their own, in one call.
### Reference
#### Reading the Menu Tree
get/api/v1/admin/website/menus
`Website/GetMenus` admin
Returns a whole menu group as a nested tree.
Query 1
groupstringWhich menu: `header`, `footer`, `clientArea`, `mobile`, `sidebar`. The header menu by default.
Response fields data[] — 11 + meta — 2
idintThe item id.
parentintThe parent item. Zero says it sits at the top level.
typestringThe menu group it belongs to.
iconstringThe item icon.
rankintWhere it sits among its siblings.
targetboolWhether the link opens in a new tab.
statusstringWhether the item is live.
pagestringThe page it points at. Empty means the link was written by hand.
only_client_areaboolWhether the item shows in the client panel alone.
languagesobjectThe title, link, description, badge and mega-menu content per language.
childrenarrayThe items beneath it. Same shape, nesting further down.
groupstringThe menu group asked for. It comes back under meta.
countintHow many items sit at the top level.
Errors 2
invalid_group422The menu group is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/menus?group=header' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/website/menus');
url.searchParams.set('group', 'header');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/menus?' . http_build_query(['group' => 'header']));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Each group is a SEPARATE tree; seeing them all takes five calls.
$header = Api::Website()->GetMenus([], ['group' => 'header'])['data'];
$footer = Api::Website()->GetMenus([], ['group' => 'footer'])['data'];
```
#### Reading the Page Options
get/api/v1/admin/website/menus/page-options
`Website/GetMenuPageOptions` admin
Returns the pages a menu item can point at.
Response fields data
dataarrayThe list of pages you can point at. The keys for the page field come from here.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/menus/page-options' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/menus/page-options', {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/menus/page-options');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Do not write the keys into your code: the list follows the installation's own pages.
$options = Api::Website()->GetMenuPageOptions()['data'];
```
#### Reordering the Menu
put/api/v1/admin/website/menus/reorder
`Website/ReorderMenus` admin order and parent together
Writes the order and the nesting of menu items in one call.
Body 1
ordersarrayreqThe new arrangement. Each entry carries an id, a position and a parent, and children nest through their own list.
Response fields data — 1
reorderedintHow many items were written. The nested ones count too.
Errors 2
orders_required422No item was sent.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/website/menus/reorder' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"orders":[{"id":10,"position":0,"parentId":0,"submenuOrder":[{"id":11,"position":0,"parentId":10}]}]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/menus/reorder', {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
orders: [
{
id: 10,
position: 0,
parentId: 0,
submenuOrder: [{ id: 11, position: 0, parentId: 10 }],
},
],
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/menus/reorder');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'orders' => [[
'id' => 10,
'position' => 0,
'parentId' => 0,
'submenuOrder' => [['id' => 11, 'position' => 0, 'parentId' => 10]],
]],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// An item you leave out STAYS PUT: a partial list can leave the tree half-moved.
$r = Api::Website()->ReorderMenus(['orders' => $tree]);
$written = $r['data']['reordered'];
```
#### Reading One Menu Item
get/api/v1/admin/website/menus/{id}
`Website/GetMenu` admin
Returns one menu item with its languages.
Response fields data — 11
idintThe item id.
parentintThe parent item. Zero says it sits at the top level.
typestringThe menu group it belongs to.
iconstringThe item icon.
rankintWhere it sits among its siblings.
targetboolWhether the link opens in a new tab.
statusstringWhether the item is live.
pagestringThe page it points at. Empty means the link was written by hand.
only_client_areaboolWhether the item shows in the client panel alone.
languagesobjectThe title, link, description, badge and mega-menu content per language.
childrenarrayThe items beneath it. Same shape, nesting further down.
Errors 2
menu_not_found404No such menu item.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/menus/10' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/menus/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/menus/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The children list comes back EMPTY here; use the group endpoint to see the tree.
$item = Api::Website()->GetMenu(['id' => $id])['data'];
```
#### Adding a Menu Item
post/api/v1/admin/website/menus
`Website/CreateMenu` admin
Adds a new item to a menu.
Body 7
groupstringreqThe menu the item goes into: `header`, `footer`, `clientArea`, `mobile`, `sidebar`.
parentintThe parent item. Left out, the item joins the top level.
pagestringThe page to point at. Left empty, you write the link by hand in the language field.
iconstringThe item icon.
targetintOpens the link in a new tab.
rankintWhere it sits among its siblings.
languagesobjectThe content per language: title, link, description, badge text with its colours, and mega-menu content.
Response fields 201 — data — 11
dataobjectThe menu item created. Same shape as the detail endpoint.
Errors 3
invalid_group422The menu group is not recognised.
create_failed500The item could not be created.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/menus' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"group":"header","page":"home","languages":{"tr":{"title":"Ana Sayfa"}}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/menus', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
group: 'header',
page: 'home',
languages: {
en: { title: 'Home', description: 'Back to homepage', label: 'New' },
},
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/menus');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'group' => 'header',
'page' => 'home',
'languages' => ['en' => ['title' => 'Home']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The title is written PER LANGUAGE; a language you leave out shows an empty label.
Api::Website()->CreateMenu([
'group' => 'header',
'page' => 'home',
'languages' => ['en' => ['title' => 'Home'], 'tr' => ['title' => 'Ana Sayfa']],
]);
```
#### Updating a Menu Item
patch/api/v1/admin/website/menus/{id}
`Website/UpdateMenu` admin
Changes the menu item fields you send.
Body 6
iconstringThe item icon.
pagestringThe page to point at.
targetintOpens the link in a new tab.
rankintWhere it sits among its siblings.
parentintThe parent item. Moves the item to another branch.
languagesobjectThe content per language: title, link, description, badge text with its colours, and mega-menu content.
Response fields data — 11
dataobjectThe item as it now stands. Same shape as the detail endpoint.
Errors 2
menu_not_found404No such menu item.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/admin/website/menus/10' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"rank":1,"languages":{"tr":{"title":"Anasayfa"}}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/menus/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
rank: 1,
languages: { en: { title: 'Homepage' } },
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/menus/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'rank' => 1,
'languages' => ['en' => ['title' => 'Homepage']],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// An item cannot move to another GROUP; the group is given at creation alone.
Api::Website()->UpdateMenu(['id' => $id, 'parent' => $newParent]);
```
#### Deleting a Menu Item
delete/api/v1/admin/website/menus/{id}
`Website/DeleteMenu` admin children go too
Removes a menu item and everything beneath it.
Response fields data — 3
deletedboolWhether the delete ran.
idintThe id of the item removed.
removedarrayEvery id removed. The children appear in this list too.
Errors 2
menu_not_found404No such menu item.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/menus/10' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/menus/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const { data } = await res.json();
console.log(data.removed); // [10, 11]
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/menus/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Deleting a parent takes the SUBMENU with it; move the children elsewhere first.
$gone = Api::Website()->DeleteMenu(['id' => $id])['data']['removed'];
```
### Pitfalls
> **A delete takes the submenu with it**
>
> Deleting a menu item also deletes **everything beneath it**. Removing a top-level heading takes every link under it out of the menu. The removed list in the response tells you what actually went, so move the children under another item first when you want to keep them.
> **An item cannot change group**
>
> The menu group is given **at creation alone**, and the update does not take it. Moving a header link into the footer means creating it again in the new group and removing the old one. The same holds for the reorder endpoint: it shifts things only within one tree.
> **The reorder covers only what you send**
>
> The reorder endpoint writes **only the items in your list**, and whatever you leave out stays where it was. Sending part of the tree and skipping the rest can leave the menu half-moved. Read the number written from the response and weigh it against what you expected.
> **The title is per language**
>
> A menu title is written separately in each language. Skip one and the item shows there with an **empty label**: it does not vanish, it stands nameless. Switch a new language on and none of the existing items carries a title in it, so you have to walk through them all.
> **A page link and a hand-written link differ**
>
> An item pointing at a page **follows it by itself** when the page address changes. A hand-written link stays as it is and breaks once the page moves. When the target is a page on your own site, use the page field instead of typing an address; the page options endpoint gives you the valid keys.
### Related Articles
- [Website Pages](https://dev.wisecp.com/en/website-pages)
- [Website Categories](https://dev.wisecp.com/en/website-categories)
- [The Contact Inbox](https://dev.wisecp.com/en/contact-inbox)
## The Contact Inbox
https://dev.wisecp.com/en/contact-inbox
The nine endpoints that read, move and answer the contact form inbox.
### Overview
Messages from the contact form behave like an **inbox**: unread, read, replied, spam and trash. These nine endpoints read that inbox, move messages between folders and carry out two real actions.
The folder is **not a stored field**; it is computed from the record's status and its read mark. Moving a message to read leaves the status alone and flips the mark instead.
Two endpoints reach outside the installation: **replying** sends the visitor a real e-mail, and **converting** opens a real support ticket. Neither can be undone.
### Reference
#### Listing the Messages
get/api/v1/admin/website/messages
`Website/GetMessages` admin
Returns the contact form messages in a folder.
Query 4
folderstringWhich folder: `unread`, `read`, `replied`, `spam`, `trash`. The unread ones by default.
searchstringSearches the messages.
pageintWhich page.
limitintRecords per page. A hundred at most.
Response fields data[] — 16 + meta — 5
idintThe message id.
full_namestringThe sender name.
emailstringThe sender e-mail.
phonestringThe sender phone.
messagestringThe message text.
ipstringThe address it came from.
langstringThe language the form was filled in.
statusstringThe record's raw status. Normal, replied, spam or trash.
folderstringThe computed folder: `unread`, `read`, `replied`, `spam`, `trash`. Derived from the status and the read mark.
unreadintThe read mark. **The logic is inverted:** zero means unread and one means read.
admin_messagestringThe text of the reply sent.
replied_byintThe administrator who replied.
replied_atstring | nullWhen the reply went out.
converted_to_ticket_idintThe ticket it became. Zero means it has not been converted.
read_byobjectWho read it and when.
created_atstring | nullWhen it was submitted.
totalintHow many the folder holds. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
folder stringThe folder listed.
next_pageintThe next page. Zero means you are on the last one.
Errors 2
invalid_folder422The folder is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/messages?folder=unread' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/admin/website/messages');
url.searchParams.set('folder', 'unread');
const res = await fetch(url, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages?' . http_build_query(['folder' => 'unread']));
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The read mark is INVERTED: zero means unread and one means read.
$msgs = Api::Website()->GetMessages([], ['folder' => 'unread'])['data'];
$isRead = $msgs[0]['unread'] === 1;
```
#### Reading One Message
get/api/v1/admin/website/messages/{id}
`Website/GetMessage` admin
Returns a single message.
Response fields data — 16
idintThe message id.
full_namestringThe sender name.
emailstringThe sender e-mail.
phonestringThe sender phone.
messagestringThe message text.
ipstringThe address it came from.
langstringThe language the form was filled in.
statusstringThe record's raw status. Normal, replied, spam or trash.
folderstringThe computed folder: `unread`, `read`, `replied`, `spam`, `trash`. Derived from the status and the read mark.
unreadintThe read mark. **The logic is inverted:** zero means unread and one means read.
admin_messagestringThe text of the reply sent.
replied_byintThe administrator who replied.
replied_atstring | nullWhen the reply went out.
converted_to_ticket_idintThe ticket it became. Zero means it has not been converted.
read_byobjectWho read it and when.
created_atstring | nullWhen it was submitted.
Errors 2
message_not_found404No such message.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/admin/website/messages/20' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/messages/${id}`, {
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Reading does NOT mark it read; the mark is set by a call of its own.
$msg = Api::Website()->GetMessage(['id' => $id])['data'];
```
#### Moving Messages in Bulk
post/api/v1/admin/website/messages/bulk-move
`Website/BulkMoveMessages` admin can block the sender
Moves several messages into another folder in one call.
Body 4
idsarrayreqThe message ids to move.
folderstringreqThe folder to move them to: `unread`, `read`, `replied`, `spam`, `trash`.
block_emailsboolAdds the sender's e-mail and phone to the banned list. It works on the spam folder alone.
report_spamboolBlocks the sender's address. It works on the spam folder alone.
Response fields data — 2
movedintHow many were moved.
folderstringThe folder they went to.
Errors 3
ids_required422No message was given.
invalid_folder422The folder is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/messages/bulk-move' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ids":[20,21],"folder":"trash"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/messages/bulk-move', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ ids: [20, 21], folder: 'trash' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/bulk-move');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['ids' => [20, 21], 'folder' => 'trash']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Two options reach PAST THE MESSAGE: the sender is banned and their address blocked.
Api::Website()->BulkMoveMessages([
'ids' => $ids,
'folder' => 'spam',
'block_emails' => true,
'report_spam' => true,
]);
```
#### Emptying a Folder
post/api/v1/admin/website/messages/empty-folder
`Website/EmptyMessageFolder` admin a permanent delete
Empties the spam or the trash folder outright.
Body 1
folderstringreqThe folder to empty. Only the spam and trash folders can be emptied.
Response fields data — 1
emptiedstringThe folder emptied.
Errors 2
invalid_folder422That folder cannot be emptied.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/messages/empty-folder' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"folder":"trash"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/admin/website/messages/empty-folder', {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ folder: 'trash' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/empty-folder');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['folder' => 'trash']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// It does NOT say how many went and cannot be undone; list the folder and count first.
$before = Api::Website()->GetMessages([], ['folder' => 'trash'])['meta']['total'];
Api::Website()->EmptyMessageFolder(['folder' => 'trash']);
```
#### Moving One Message
put/api/v1/admin/website/messages/{id}/folder
`Website/SetMessageFolder` admin
Moves one message into another folder.
Body 3
folderstringreqThe folder to move it to: `unread`, `read`, `replied`, `spam`, `trash`.
block_emailsboolAdds the sender to the banned list.
report_spamboolBlocks the sender's address.
Response fields data — 16
dataobjectThe message as it now stands. Same shape as the detail endpoint.
Errors 3
message_not_found404No such message.
invalid_folder422The folder is not recognised.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/admin/website/messages/20/folder' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"folder":"read"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/messages/${id}/folder`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ folder: 'read' }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/' . $id . '/folder');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['folder' => 'read']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The read and unread folders leave the STATUS alone and flip the read mark instead.
Api::Website()->SetMessageFolder(['id' => $id, 'folder' => 'read']);
```
#### Marking a Message Read
post/api/v1/admin/website/messages/{id}/read
`Website/ReadMessage` admin
Marks a message read and records who read it.
Body —
——No body is needed. The message comes from the path; send an empty body.
Response fields data — 16
dataobjectThe message as it now stands. The administrator joins the readers map.
Errors 2
message_not_found404No such message.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/messages/20/read' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/messages/${id}/read`, {
method: 'POST',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/' . $id . '/read');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The readers map keeps EACH administrator apart, while the mark is one for the panel.
Api::Website()->ReadMessage(['id' => $id]);
```
#### Replying to a Message
post/api/v1/admin/website/messages/{id}/reply
`Website/ReplyMessage` admin a real e-mail goes out
Sends the visitor an e-mail reply and moves the message to replied.
Body 3
messagestringreqThe reply text to send.
save_as_templateintKeeps the reply for later use.
template_namestringThe name to keep it under. Needed when you ask for it to be kept.
Response fields data — 16
dataobjectThe message as it now stands. Its status becomes replied.
Errors 5
message_not_found404No such message.
message_required422The reply text is empty.
template_name_required422Keeping was asked for with no name given.
reply_failed422The e-mail could not be sent.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/messages/20/reply' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"message":"Ilginiz icin tesekkurler, en kisa surede donecegiz."}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/messages/${id}/reply`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
message: "Thanks for reaching out - we'll get back to you shortly.",
}),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/' . $id . '/reply');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'message' => 'Thanks for reaching out.',
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This call MAILS THE VISITOR and cannot be undone; check the text before sending.
Api::Website()->ReplyMessage([
'id' => $id,
'message' => $text,
]);
```
#### Turning It into a Ticket
post/api/v1/admin/website/messages/{id}/convert-to-ticket
`Website/ConvertMessageToTicket` admin opens a real ticket
Opens a support ticket from a message and ties the two together.
Body 4
departmentintreqThe department the ticket goes to.
priorityintThe ticket priority.
staffintThe administrator to assign the ticket to.
notesstringAn internal note for the ticket.
Response fields data — 2
ticket_idintThe ticket opened.
message_idintThe message it came from.
Errors 5
message_not_found404No such message.
department_required422No department was given.
blocked_by_gate422A hook refused the conversion.
ticket_failed500The ticket could not be opened.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/admin/website/messages/20/convert-to-ticket' \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-d '{"department":1,"priority":2}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/messages/${id}/convert-to-ticket`, {
method: 'POST',
headers: {
Authorization: `Bearer ${apiKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ department: 1, priority: 2 }),
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/' . $id . '/convert-to-ticket');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['department' => 1, 'priority' => 2]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The message CARRIES which ticket it became; read that before converting again.
$msg = Api::Website()->GetMessage(['id' => $id])['data'];
if ($msg['converted_to_ticket_id'] === 0)
Api::Website()->ConvertMessageToTicket(['id' => $id, 'department' => 1]);
```
#### Deleting a Message
delete/api/v1/admin/website/messages/{id}
`Website/DeleteMessage` admin
Removes one message for good.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the message removed.
Errors 2
message_not_found404No such message.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/admin/website/messages/20' \
-H "Authorization: Bearer $API_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/admin/website/messages/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/admin/website/messages/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $apiKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Move it to TRASH rather than delete: the record stays and can come back if needed.
Api::Website()->SetMessageFolder(['id' => $id, 'folder' => 'trash']);
```
### Pitfalls
> **The read mark runs backwards**
>
> In the read field **zero means unread and one means read**. The name suggests the opposite, so the logic here often gets read backwards and the inbox count comes out wrong. Test against one rather than trusting the value as a boolean.
> **The folder is computed rather than stored**
>
> What the record holds is the **status and the read mark**, and the folder is derived from those two. Moving a message to read leaves the status alone and flips the mark, while moving it to spam or trash changes the status. When filtering on your side, use the computed field rather than the raw status.
> **Moving to spam can block the sender**
>
> Two options on the move calls reach **far past the message**: one adds the sender's e-mail and phone to the banned list, the other blocks their address. Both apply across the installation and keep that person from using the form again. Leave them off when doing a bulk clean-up.
> **The reply really goes out**
>
> The reply endpoint saves no draft; it sends the visitor a **real e-mail**, and a sent message cannot be pulled back. The convert endpoint likewise opens a real ticket. When trying these two from a script, use a test record that reaches your own address.
> **Emptying a folder is permanent and gives no count**
>
> The empty call works on the spam and trash folders alone, yet there it **removes everything for good** and does not say how many went. The response names only the folder emptied. When you need a record, list the folder before emptying it.
### Related Articles
- [Customer Testimonials](https://dev.wisecp.com/en/customer-testimonials)
- [Managing Tickets](https://dev.wisecp.com/en/managing-tickets)
- [Website Pages](https://dev.wisecp.com/en/website-pages)
# API / Client API
## Client API Overview
https://dev.wisecp.com/en/client-api-overview
The surface a customer uses on their own account, and the ways it deliberately differs from the admin one.
### Overview
The client API lets a customer drive their own account from their own code: read services, pay an invoice, order a domain, open a ticket. The key belongs to the customer, not to you, and the customer issues it from their account.
Everything it reaches is bounded to that one account. The scope is not a filter you remember to apply; it comes from the key and cannot be widened by anything in the request.
It is a separate product from the admin surface, not a restricted view of it. Different address, different kind of key, and a shorter catalogue built from what a customer can actually do in their panel.
### Prerequisites
- A customer account on the installation, and a client key issued from `/api-credentials` in that account.
- The base address `/api/v1/client`. An admin key sent here is refused, and so is a client key sent to the admin surface.
### Structure
Four things behave differently here, and knowing them up front saves reading two catalogues side by side.
- **Every query is account-bound**: A record belonging to someone else answers `404`, exactly like a record that does not exist. The two are never distinguished, so a key cannot probe for its neighbours.
- **Universal values travel as codes**: Countries are ISO two-letter codes and currencies are ISO codes, in both directions. Internal numeric ids are not part of this surface.
- **Money is an object, dates are plain**: Amounts arrive as `{amount, currency}` rather than a formatted string, and dates as `YYYY-MM-DD` or null. Formatting is yours to do.
- **Anything a form would pick has a lookup**: Where the panel offers a dropdown, the API offers a reference endpoint: countries, then that country's states, then that state's cities.
#### What Stays in the Panel
Some account work has no endpoint at all, and that is a boundary rather than a gap. Card storage needs the payment provider's own hosted flow. Changing a password or an email address needs a one-time code. Two-factor setup and identity documents need a person. Data-deletion requests are a legal decision.
Their *state* is still readable, so an integration can tell whether an account is verified without being able to verify it.
### Example
```bash
curl -H 'Authorization: Bearer wck_...' \
'https://panel.example.com/api/v1/client/whoami'
# {"data":{"id":3,"type":"client","owner_id":42,"permissions":["Services/*"]}}
curl -H 'Authorization: Bearer wck_...' \
'https://panel.example.com/api/v1/client/services?limit=10'
```
### Pitfalls
> **Do not build an operator tool on client keys**
>
> Serving many customers from one integration means one key per customer, each issued by that customer. If you need to act across accounts, that is the admin surface. Collecting customers' keys to fake it is a liability you do not want to hold.
> **Payment is balance or a stored card, nothing else**
>
> Ordering and paying accept the account balance or a card the customer already saved. Gateway flows that need a redirect, an iframe or a 3-D Secure step belong to the panel. A declined card still answers `200` with a failed payment on it, so read the payment status, not only the HTTP code.
### Related Articles
- [The WISECP API](https://dev.wisecp.com/en/the-wisecp-api)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
- [Request and Response Format](https://dev.wisecp.com/en/request-and-response-format)
- [Client API First Calls](https://dev.wisecp.com/en/client-api-first-calls)
## Client API First Calls
https://dev.wisecp.com/en/client-api-first-calls
The five endpoints called while connecting to the client surface.
### Overview
The client API is for a customer managing their own account from an integration. It is a surface apart from the admin API: **a different address and a different kind of key**, with every call bounded to one customer.
This article answers the first three questions: is the surface up, what can my key do, and which values fill the address fields.
The address chain runs one way: the country code first, then the state number, then the city number. Each step wants the one before it, and any of them can come back empty.
### Reference
#### The Health Check
get/api/v1/admin/client/ping
`System/Ping` no key needed
Returns that the client surface is up, along with the server time.
Response fields data — 3
pongboolWhether the surface is up.
versionstringThe API version.
timestringThe server's time. It comes in the server's own time zone.
Errors —
——This endpoint is open to everyone and returns no error.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/ping'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/ping');
const { data } = await res.json();
if (! data.pong) reportOutage();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/ping');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This is SEPARATE from the admin surface's endpoint of the same name; one can be up while the other is not.
$up = Kernel::internal('client:System/Ping')['data']['pong'] ?? false;
```
#### What the Key Is
get/api/v1/admin/client/whoami
`System/Whoami` no scope needed
Returns the key's identity, its permissions and the client it belongs to.
Response fields data — 6
idintThe key id.
typestringThe key kind. On this surface it is always a client key.
namestringThe name the key was given.
permissionsstring[]The scopes the key carries.
last_accessstringWhen it was last used.
owner_idintThe client the key belongs to. Every call is bounded by this client.
Errors 4
missing_token401The key was not sent or is not known.
key_revoked401The key was revoked.
audience_mismatch403An admin key was used on the client surface.
ip_not_allowed403The request came from outside the addresses allowed.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/whoami' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/whoami', {
headers: { Authorization: `Bearer ${clientKey}` },
});
if (res.status === 403) return showWrongSurface();
const { data } = await res.json();
console.log(data.owner_id, data.permissions);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/whoami');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// owner_id IS NOT PASSED on calls: the client comes from the key and writing it in the body changes nothing.
$me = Kernel::internal('client:System/Whoami', ['owner_id' => $ownerId])['data'];
```
#### The Countries
get/api/v1/admin/client/reference/countries
`Reference/GetCountries` no scope needed
Returns the country codes the profile and address endpoints take.
Response fields data[] — 2
codestringThe two-letter country code. The profile and address endpoints want this rather than a number.
namestringThe country name. It comes in the site's language.
Errors 3
missing_token401The key was not sent or is not known.
key_revoked401The key was revoked.
audience_mismatch403An admin key was used on the client surface.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/reference/countries' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/reference/countries', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
renderCountryPicker(data);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/reference/countries');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The client surface speaks the COUNTRY CODE; the country NUMBER from the admin surface is not taken here.
$rows = Kernel::internal('client:Reference/GetCountries', ['owner_id' => $uid])['data'];
$codes = array_column($rows, 'code');
```
#### A Country's States
get/api/v1/admin/client/reference/countries/{code}/states
`Reference/GetStates` no scope needed
Returns a country's states with the numbers the address fields use.
Response fields data[] — 2
idintThe state number. It is the state field on the address endpoints and the input to the city lookup.
namestringThe state name.
Errors 4
not_found404No such country code.
missing_token401The key was not sent or is not known.
key_revoked401The key was revoked.
audience_mismatch403An admin key was used on the client surface.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/reference/countries/TR/states' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/reference/countries/${code}/states`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (! data.length) useFreeTextState();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/reference/countries/' . $code . '/states');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// AN EMPTY list is normal: with no states on that country the address field takes free text.
$states = Kernel::internal('client:Reference/GetStates', ['owner_id' => $uid, 'code' => $code])['data'];
$free = ! $states;
```
#### A State's Cities
get/api/v1/admin/client/reference/states/{id}/cities
`Reference/GetCities` no scope needed
Returns a state's cities with the numbers the address fields use.
Response fields data[] — 2
idintThe city number. It is the city field on the address endpoints.
namestringThe city name.
Errors 4
not_found404No such state.
missing_token401The key was not sent or is not known.
key_revoked401The key was revoked.
audience_mismatch403An admin key was used on the client surface.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/reference/states/34/cities' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/reference/states/${stateId}/cities`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/reference/states/' . $stateId . '/cities');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A CITY IS REQUIRED on an address even when the list is empty: write free text rather than leaving it out.
$cities = Kernel::internal('client:Reference/GetCities', ['owner_id' => $uid, 'id' => $stateId])['data'];
```
### Pitfalls
> **An admin key does not work on this surface**
>
> The client surface takes a client key alone, and calling with an admin key gives `audience_mismatch`. That code means the **wrong surface** rather than a missing permission, so fixing the address instead of the key wastes time.
> **The customer comes from the key and never from the request**
>
> Every client endpoint is bounded by the key's owner. Writing a customer number into the body **changes nothing**, and asking for someone else's record answers not found. Use the admin surface when you need to reach more than one customer.
> **The country speaks a code while the state and city speak numbers**
>
> On the client surface a country is given as a **two-letter code** and the country number from the admin surface is not taken. The state and city want numbers. Filling all three the same way leads to a quiet validation error.
> **An empty list is not an error but a sign to use free text**
>
> The state or city list can come back empty when the platform holds no data for that country or state. The address field then takes **free text**. A city stays required even with an empty list, and an address does not save without one.
> **The health check does not verify the key**
>
> The health endpoint wants no credentials, so a **successful answer** says nothing about your key working. Call both while wiring an integration up: the health endpoint proves the server and the key endpoint proves the credentials.
### Related Articles
- [Account Details](https://dev.wisecp.com/en/the-account-of-the-key)
- [The Address Book](https://dev.wisecp.com/en/the-address-book)
## The Account Behind the Key
https://dev.wisecp.com/en/the-account-of-the-key
The five endpoints giving the profile, choices and security state of the key's owner.
### Overview
On the client API the account is always **resolved from the key**. There is no customer parameter: these five endpoints read and write the record of whoever owns the key.
What may be changed on a profile is **the operator's decision**. The read endpoint returns that decision alongside the data: which fields are open and which cannot be emptied.
Account security is deliberately left out. The password, the e-mail, two-step sign-in and ending a session **stay in the panel**. The API shows their state alone.
### Reference
#### Reading the Profile
get/api/v1/admin/client/me
`Account/GetMe` the key's owner
Returns the profile of the customer the key belongs to.
Response fields data — 25 + meta — 2
idintThe customer id.
kindstringThe account kind: a person or a company.
full_namestringThe first and last name together.
namestringThe first name.
surnamestringThe last name.
companyobject companyThe company details.
namestringThe company name.
tax_numberstringThe tax number.
tax_officestringThe tax office.
avatar_urlstringThe address of the profile picture. It comes empty when there is none.
emailstringThe e-mail address.
email_verifiedboolWhether the e-mail was verified.
phonestringThe mobile number. It comes in international form.
phone_country_codestringThe phone's country code.
phone_verifiedboolWhether the number was verified.
landline_phonestringThe landline number.
identitystringThe identity number.
birthdaystringThe date of birth.
languagestringThe language chosen.
countrystringThe country code.
currencystringThe display currency. It can differ from the wallet's.
group_idintThe customer group id.
balanceobjectThe wallet balance. It carries an amount and a currency, and that currency is the **wallet's own**.
timezonestringThe time zone chosen. Empty means the installation's is used.
date_formatstringThe date format chosen.
custom_fieldsarrayThe extra fields the operator defined. Each carries an id, name, type, whether it is required, whether it is editable, its choices and its value.
created_atstringWhen the account was opened.
last_login_atstringWhen they last signed in.
editablearrayThe field names that can be changed now. It comes back under meta.
requiredarrayThe fields that cannot be emptied once sent.
Errors 4
missing_token401The key was not sent or is not known.
insufficient_scope403The key lacks the required scope.
audience_mismatch403An admin key was used on the client surface.
not_found404The account behind the key is gone.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/me' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/me', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data, meta } = await res.json();
renderForm(data, meta.editable, meta.required);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/me');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Build the form from meta.editable: a field the operator closed gives 422 rather than passing quietly.
$r = Kernel::internal('client:Account/GetMe', ['owner_id' => $uid]);
$form = array_intersect_key($r['data'], array_flip($r['meta']['editable']));
```
#### Updating the Profile
patch/api/v1/admin/client/me
`Account/UpdateMe` an operator gate
Changes the profile fields you send.
Body 14
namestringThe first name. It cannot be emptied.
surnamestringThe last name. It cannot be emptied.
kindstringThe account kind. Moving to a person clears the company details.
companyobjectThe company details. It wants the account to be a company.
phonestringThe mobile number. Changing it drops the verified mark.
birthdaystringThe date of birth.
identitystringThe identity number.
landline_phonestringThe landline number.
languagestringThe language code. It has to exist on the installation.
countrystringThe country code.
currencystringThe display currency code.
timezonestringThe time zone. Sending it empty clears the account's own choice.
date_formatstringThe date format. Sending it empty clears the account's own choice.
custom_fieldsobjectThe values of the extra fields. A tick field takes a list.
avatarstringThe profile picture. Encoded content alone is taken and an address is refused.
Response fields data — 25 + meta — 1
dataobjectThe profile as it now stands. Same shape as the read endpoint.
changedarrayThe fields truly written. It comes back under meta.
Errors 12
field_not_editable422The field is closed by an operator setting.
nothing_to_update422The body holds no field that is known.
name_required422The first or last name cannot be emptied.
kind_invalid422The account kind is neither of the two values.
company_requires_corporate422Company details were sent to a personal account.
company_name_required422A required part of the company is empty.
phone_required422The phone was emptied while required.
phone_taken422The number is used on another account.
birthday_required422A required field was emptied.
language_invalid422An unknown preference value. The country, currency, time zone and date format are refused the same way.
custom_field_required422An unknown or required extra field.
avatar_url_not_allowed422An address was sent as the picture.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/client/me' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"timezone":"Europe/Istanbul","date_format":"d/m/Y"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/me', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ timezone: 'Europe/Istanbul' }),
});
const { meta } = await res.json();
console.log(meta.changed);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/me');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['timezone' => 'Europe/Istanbul']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The E-MAIL and PASSWORD do not change here: both want a verification flow and stay in the panel.
$r = Kernel::internal('client:Account/UpdateMe', ['owner_id' => $uid, 'timezone' => $tz]);
$written = $r['meta']['changed'];
```
#### Reading the Notification Choices
get/api/v1/admin/client/me/notifications
`Account/GetNotifications` client
Returns which notifications the account takes and by which channel.
Response fields data — 1
categoriesarray categories[]One row per category.
categorystringThe category name: general, invoices, support, product, domain or marketing.
emailboolWhether the e-mail channel is on.
smsboolWhether the message channel is on.
lockedboolWhether the category can be closed. The general one is always on.
Errors 3
missing_token401The key was not sent or is not known.
insufficient_scope403The key lacks the required scope.
audience_mismatch403An admin key was used on the client surface.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/me/notifications' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/me/notifications', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const editable = data.categories.filter((c) => ! c.locked);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/me/notifications');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Read BEFORE writing: the write is a FULL REPLACE and a category left out closes on both channels.
$cur = Kernel::internal('client:Account/GetNotifications', ['owner_id' => $uid])['data'];
```
#### Writing the Notification Choices
put/api/v1/admin/client/me/notifications
`Account/UpdateNotifications` a full replace
Rewrites the notification choices in full.
Body 5
invoicesobjectThe invoice notifications. It carries the e-mail and message channels, and a channel left out counts as off.
supportobjectThe support notifications.
productobjectThe product and service notifications.
domainobjectThe domain notifications.
marketingobjectThe marketing notifications.
Response fields data — 1
dataobjectThe choices as they now stand. Same shape as the read endpoint.
Errors 3
missing_token401The key was not sent or is not known.
insufficient_scope403The key lacks the required scope.
audience_mismatch403An admin key was used on the client surface.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/me/notifications' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"invoices":{"email":true,"sms":false},"support":{"email":true,"sms":true}}'
```
```javascript
const cur = await fetch('https://panel.example.com/api/v1/client/me/notifications', {
headers: { Authorization: `Bearer ${clientKey}` },
}).then((r) => r.json());
const body = {};
for (const c of cur.data.categories)
if (! c.locked) body[c.category] = { email: c.email, sms: c.sms };
body.marketing = { email: false, sms: false };
await fetch('https://panel.example.com/api/v1/client/me/notifications', {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/me/notifications');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($prefs),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A category you leave out CLOSES: send the full set even to change one choice.
$cur = Kernel::internal('client:Account/GetNotifications', ['owner_id' => $uid])['data'];
$body = [];
foreach ($cur['categories'] as $c)
if (! $c['locked']) $body[$c['category']] = ['email' => $c['email'], 'sms' => $c['sms']];
$body['marketing'] = ['email' => false, 'sms' => false];
Kernel::internal('client:Account/UpdateNotifications', ['owner_id' => $uid] + $body);
```
#### Reading the Security Summary
get/api/v1/admin/client/me/security
`Account/GetSecurity` read only
Returns the verification state, the two-step sign-in and the recent sessions.
Response fields data — 5
email_verifiedboolWhether the e-mail was verified.
phone_verifiedboolWhether the number was verified.
two_factorobject two_factorWhere two-step sign-in stands.
enabledboolWhether it is on.
methodstringWhich method. An app, e-mail or a message.
sessionsarray sessions[]The sign-ins of the last thirty days. 25 records at most, newest first.
ipstringThe address it came from.
citystringThe city caught at sign-in.
country_codestringThe country code.
user_agentstringThe browser string. It comes raw and parsing is left to you.
created_atstringWhen they signed in.
last_login_atstringWhen they last signed in.
Errors 3
missing_token401The key was not sent or is not known.
insufficient_scope403The key lacks the required scope.
audience_mismatch403An admin key was used on the client surface.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/me/security' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/me/security', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (! data.two_factor.enabled) nudgeToEnable();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/me/security');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// It is READ ONLY: signing a session out, the password and setting two-step up are ABSENT here and stay in the panel.
$sec = Kernel::internal('client:Account/GetSecurity', ['owner_id' => $uid])['data'];
$stale = array_filter($sec['sessions'], fn ($s) => $s['country_code'] !== $home);
```
### Pitfalls
> **Writing the notifications is a full replace**
>
> The notification write reads the body as the **whole set** of choices. A category you leave out closes on both the e-mail and the message channel. Read the current list first and write over it to change one. The general category is locked and stays as it is even when sent.
> **A closed field is not ignored quietly**
>
> Sending a field the operator closed for editing is refused with `422`. Building a form from a fixed field list makes the **whole save fail** the day one of them is closed. Always build the list from the editable set the read endpoint returns.
> **The wallet currency is not the display choice**
>
> The currency field on the profile says **how amounts are shown**, while the wallet's own currency comes separately inside the balance object. The two can differ, and reading the balance in the display currency gives a wrong figure. Read the balance in its own currency.
> **The profile picture goes as content alone**
>
> The picture field **takes no address**. The server never fetches one you give, because the outgoing request would give away its real address. Send the image as encoded content, and send it empty to remove the picture.
> **Changing the phone drops its verification**
>
> The verified mark is **cleared** when the number changes. The flows resting on the phone stop until the new one is verified. The same holds for the e-mail, which cannot be changed here at all. Send the customer to verification after a number change.
> **The security endpoint is not a management tool**
>
> The security summary lists the sessions and **cannot end them**, and no session token is ever returned. The password, two-step sign-in and identity documents stay in the panel for the same reason: each wants an unbroken human step.
### Related Articles
- [The Address Book](https://dev.wisecp.com/en/the-address-book)
- [Client API First Calls](https://dev.wisecp.com/en/client-api-first-calls)
- [The Account Balance](https://dev.wisecp.com/en/the-account-balance)
## The Address Book
https://dev.wisecp.com/en/the-address-book
The six endpoints managing the account's billing profiles.
### Overview
The address book holds the account's **billing profiles**. Each record carries a contact, an address and the tax rate that address falls under, and the invoices are raised from it.
One profile is always the **default** and the account never sits without one: the first added becomes it, and removing the default promotes the next in line.
The location fields are filled from the reference chain: a country code, a state number and a city number. Where the platform holds no data the same fields take free text.
### Reference
#### Listing the Addresses
get/api/v1/client/addresses
`Addresses/GetAddresses` the key's owner
Returns the account's billing profiles.
Response fields data[] — 18
idintThe address id.
labelstringA free label.
full_namestringThe contact's full name.
namestringThe first name.
surnamestringThe last name.
kindstringThe contact kind: a person or a company.
emailstringThe contact's e-mail.
phonestringThe contact's phone.
identitystringThe identity number.
companyobjectThe company details. It carries the name, tax number and tax office.
countrystringThe country code.
stateobjectThe state. It carries a number and a name, and the number is zero when it was typed free.
cityobjectThe city. It carries a number and a name, and the number is zero when it was typed free.
addressstringThe street address.
zipcodestringThe postcode.
tax_ratefloatThe tax rate this address falls under. The server works it out from the address.
is_defaultboolWhether it is the default billing profile.
notificationsarrayThe notification channels per contact. An e-mail and a message flag for each of the six categories.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/addresses' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/addresses', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const billing = data.find((a) => a.is_default);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/addresses');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The default contact ALWAYS comes first; take the first row rather than searching for it.
$rows = Kernel::internal('client:Addresses/GetAddresses', ['owner_id' => $uid])['data'];
$default = $rows[0] ?? null;
```
#### Reading One Address
get/api/v1/client/addresses/{id}
`Addresses/GetAddress` the key's owner
Returns one of the account's addresses.
Response fields data — 18
dataobjectThe address record. Same shape as an item in the listing.
Errors 2
not_found404No such address, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/addresses/12' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/addresses/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
if (res.status === 404) return notYours();
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/addresses/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Someone else's address also answers NOT FOUND: this endpoint never says whether it exists.
$a = Kernel::internal('client:Addresses/GetAddress', ['owner_id' => $uid, 'id' => $id]);
```
#### Adding an Address
post/api/v1/client/addresses
`Addresses/CreateAddress` a billing profile
Adds a new billing profile to the account.
Body 16
namestringreqThe contact's first name.
surnamestringreqThe last name.
emailstringreqA valid e-mail.
countrystringreqThe country code. Taken from the reference endpoint.
statestringreqThe state. A number from the list, or free text when the list is empty.
citystringreqThe city. A number from the list, or free text when the list is empty.
addressstringreqThe street address.
zipcodestringreqThe postcode. Twenty characters at most.
kindstringThe contact kind. A person by default.
companyobjectThe company details. The name is required on a company contact.
labelstringA free label.
phonestringThe contact's phone.
identitystringThe identity number.
notificationsobjectThe channel matrix. A full replace, and leaving it out opens every one.
is_defaultboolMake this the default profile.
overwrite_invoicesboolRewrite the open invoices to this address.
Response fields data — 18
dataobjectThe address made. Same shape as the read endpoint.
Errors 6
name_required422A required field is missing or invalid. The last name, e-mail, country, state, city, address and postcode are refused the same way.
company_name_required422The company name is empty on a company contact.
notifications_invalid422The notification matrix is broken or holds an unknown category.
contact_rejected422A hook refused the save.
address_add_failed500The address could not be added.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/addresses' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Jane","surname":"Cooper","email":"jane@example.com","country":"TR","state":"34","city":"1441","address":"Sample St 42","zipcode":"34710"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/addresses', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Jane', surname: 'Cooper', email: 'jane@example.com',
country: 'TR', state: String(stateId), city: String(cityId),
address: 'Sample St 42', zipcode: '34710',
}),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/addresses');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($contact),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The FIRST address becomes the DEFAULT by itself; the account never sits without a profile.
$a = Kernel::internal('client:Addresses/CreateAddress', ['owner_id' => $uid] + $contact)['data'];
$isFirst = $a['is_default'];
```
#### Updating an Address
put/api/v1/client/addresses/{id}
`Addresses/UpdateAddress` the whole body
Rewrites the address in full.
Body 16
namestringreqThe contact's first name.
surnamestringreqThe last name.
emailstringreqA valid e-mail.
countrystringreqThe country code. Taken from the reference endpoint.
statestringreqThe state. A number from the list, or free text when the list is empty.
citystringreqThe city. A number from the list, or free text when the list is empty.
addressstringreqThe street address.
zipcodestringreqThe postcode. Twenty characters at most.
kindstringThe contact kind. A person by default.
companyobjectThe company details. The name is required on a company contact.
labelstringA free label.
phonestringThe contact's phone.
identitystringThe identity number.
notificationsobjectThe channel matrix. A full replace, and leaving it out opens every one.
is_defaultboolMake this the default profile.
overwrite_invoicesboolRewrite the open invoices to this address.
Response fields data — 18
dataobjectThe address as it now stands. Same shape as the read endpoint.
Errors 5
not_found404No such address, or it belongs to another customer.
name_required422A required field is missing or invalid.
company_name_required422The company name is empty on a company contact.
contact_rejected422A hook refused the save.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/addresses/12' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Jane","surname":"Cooper","email":"jane@example.com","country":"TR","state":"34","city":"1441","address":"New St 7","zipcode":"34710"}'
```
```javascript
const cur = await fetch(`https://panel.example.com/api/v1/client/addresses/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
}).then((r) => r.json());
const body = {
...cur.data,
state: String(cur.data.state.id || cur.data.state.name),
city: String(cur.data.city.id || cur.data.city.name),
address: 'New St 7',
};
await fetch(`https://panel.example.com/api/v1/client/addresses/${id}`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/addresses/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($contact),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The state and city are read as OBJECTS and sent as PLAIN VALUES: pull the number out before writing back.
$a = Kernel::internal('client:Addresses/GetAddress', ['owner_id' => $uid, 'id' => $id])['data'];
$a['state'] = (string) ($a['state']['id'] ?: $a['state']['name']);
$a['city'] = (string) ($a['city']['id'] ?: $a['city']['name']);
Kernel::internal('client:Addresses/UpdateAddress', ['owner_id' => $uid, 'id' => $id] + $a);
```
#### Moving the Default
post/api/v1/client/addresses/{id}/default
`Addresses/SetDefaultAddress` the account country follows
Makes this address the default billing profile.
Body —
——No body is needed, send an empty one. The address comes from the id in the path.
Response fields data — 18
dataobjectThe address that is now the default.
Errors 2
not_found404No such address, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/addresses/12/default' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/addresses/${id}/default`, {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/addresses/' . $id . '/default');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// There is no way to UNSET a default: making another address the default is the only road.
Kernel::internal('client:Addresses/SetDefaultAddress', ['owner_id' => $uid, 'id' => $other]);
```
#### Removing an Address
delete/api/v1/client/addresses/{id}
`Addresses/DeleteAddress` the key's owner
Removes an address and hands the default on where needed.
Response fields data — 2
deletedboolWhether the delete ran.
idintThe id of the address removed.
Errors 2
not_found404No such address, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/addresses/12' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/addresses/${id}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${clientKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/addresses/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Removing the default is NOT refused: the next address is promoted to default by itself.
Kernel::internal('client:Addresses/DeleteAddress', ['owner_id' => $uid, 'id' => $id]);
$now = Kernel::internal('client:Addresses/GetAddresses', ['owner_id' => $uid])['data'][0] ?? null;
```
### Pitfalls
> **The state and city read as objects and write as plain values**
>
> The read endpoints return the state and city as an **object carrying a number and a name**, while the write endpoints expect a plain value. Sending a record straight back fails validation on those two fields. Pull the number out before writing, and send the name where the number is zero.
> **The update wants the whole record**
>
> The update body is the **whole address**: the fields required on create are required here as well. Send the full record even to change the postcode alone. The one ease is the notification matrix, which keeps its saved value when left out.
> **Moving the default changes the account country**
>
> Making an address the default pulls the account's country to **that address's country**. The country decides the tax rate and what some products show, so a simple-looking change can move prices. Think it through before defaulting a profile in another country.
> **Rewriting the open invoices is a choice**
>
> While adding an address you can ask for the open invoices to move to it. Without that the invoices raised on the **old address** stay as they are and the customer sees two different addresses. Consider it on a change such as a new tax number.
> **Someone else's address answers not found**
>
> Asking for another customer's address id answers `404` rather than a permission error. That is deliberate: the answer never reveals **whether that id exists**. Do not read a not-found as "it was removed".
> **Every contact carries its own notification matrix**
>
> The notification choices are kept at the account level and **per contact**: invoices can reach one person and support another. With the matrix left out a create opens every channel while an update keeps what was saved.
### Related Articles
- [The Account Behind the Key](https://dev.wisecp.com/en/the-account-of-the-key)
- [Client API First Calls](https://dev.wisecp.com/en/client-api-first-calls)
- [Paying an Invoice](https://dev.wisecp.com/en/paying-an-invoice)
## Balance
https://dev.wisecp.com/en/the-account-balance
The three endpoints giving the prepaid balance, its movements and the collection settings.
### Overview
The wallet is the account's prepaid balance. It can pay an invoice, and renewals can be taken from it **by themselves** when asked.
Three endpoints answer three questions: how much is there, where the money went and how collection should work.
The wallet has a currency of its own and it is **separate** from the display choice on the profile. Always read an amount together with the currency beside it.
### Reference
#### Reading the Wallet
get/api/v1/client/balance
`Balance/GetBalance` always fresh
Returns the wallet, the automatic payment setting and the warning setup in one call.
Response fields data — 4
balanceobjectWhat the wallet holds. It is fresh on every read and never from a cache.
low_balanceboolWhether the balance sits under the warning threshold.
auto_payobject auto_payWhere automatic payment stands.
from_balanceboolWhether renewals are taken from the wallet.
availableboolWhether the installation offers it. It rests on the operator's balance module.
backup_cardobjectThe card charged when the wallet falls short. It carries an id, a brand and the last four digits.
alertobject alertThe low balance warning.
enabledboolWhether the warning is on.
thresholdobjectThe warning threshold. It comes in the wallet's currency.
recipientsobject[]Who gets the warning. The row numbered zero is the account owner and cannot be closed; the rest are billing addresses.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/balance' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/balance', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.low_balance) promptTopUp(data.balance);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/balance');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The wallet currency can differ from the DISPLAY one on the profile; read the amount in its own.
$w = Kernel::internal('client:Balance/GetBalance', ['owner_id' => $uid])['data'];
$amount = $w['balance']['amount'];
$cur = $w['balance']['currency'];
```
#### Reading the Wallet Movements
get/api/v1/client/balance/transactions
`Balance/GetBalanceTransactions` the key's owner
Returns what came into the wallet and what left it, newest first.
Query 4
pageintWhich page.
limitintRows per page. 100 at the most.
typestringThe direction filter: money in or money out.
searchstringSearches the movement note.
Response fields data[] — 6 + meta — 4
transaction_idintThe movement id.
typestringIts direction: in or out.
amountobjectThe amount and its currency.
descriptionstringThe movement note. It usually carries an invoice number.
invoice_idintThe invoice closed. It fills when the movement closed one.
created_atstringWhen the movement happened.
totalintHow many movements there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page. Zero on the last one.
Errors 2
type_invalid422The direction filter is neither of the two values.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/balance/transactions?type=down&limit=50' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const url = new URL('https://panel.example.com/api/v1/client/balance/transactions');
url.searchParams.set('type', 'down');
const res = await fetch(url, { headers: { Authorization: `Bearer ${clientKey}` } });
const { data, meta } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/balance/transactions?type=down');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A movement is a HISTORICAL record: a refund adds a row the other way rather than removing the old one.
$rows = Kernel::internal('client:Balance/GetBalanceTransactions',
['owner_id' => $uid, 'type' => 'down'])['data'];
$paid = array_column($rows, 'invoice_id');
```
#### Changing the Wallet Settings
patch/api/v1/client/balance/settings
`Balance/UpdateBalanceSettings` it reaches the invoices
Sets automatic payment and the low balance warning.
Body 4
auto_pay_from_balanceboolWhether renewals are taken from the wallet. Changing it makes the open renewal invoices follow the new choice at once.
backup_card_idintThe card charged when the wallet falls short. Sending zero clears the card chain entirely.
alertobjectThe warning block. It carries an on flag and a threshold, and turning it on wants a positive threshold.
alert_recipientsint[]The billing address ids that get the warning. The list replaces, and the account owner never appears in it and always gets it.
Response fields data — 4
dataobjectThe wallet as it now stands. Same shape as the read endpoint.
Errors 6
not_found404The backup card is none of this account's saved cards.
nothing_to_update422The body holds no field that can be updated.
auto_pay_invalid422The automatic payment field is of the wrong kind.
card_expired422The backup card has expired.
alert_invalid422The warning block is broken or the threshold is missing.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/client/balance/settings' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"auto_pay_from_balance":true,"alert":{"enabled":true,"threshold":50}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/balance/settings', {
method: 'PATCH',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
alert: { enabled: true, threshold: 50 },
alert_recipients: [84],
}),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/balance/settings');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['auto_pay_from_balance' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The recipient list REPLACES: read the ones already on and merge before adding an address.
$cur = Kernel::internal('client:Balance/GetBalance', ['owner_id' => $uid])['data'];
$on = array_column(array_filter($cur['alert']['recipients'],
fn ($r) => $r['enabled'] && ! $r['owner']), 'id');
$on[] = $newAddressId;
Kernel::internal('client:Balance/UpdateBalanceSettings',
['owner_id' => $uid, 'alert_recipients' => $on]);
```
### Pitfalls
> **The wallet currency is not the display choice**
>
> The wallet lives in **its own currency** while the one on the profile says how amounts are shown. The two can differ, and reading the balance in the display currency gives a wrong figure. The warning threshold is in the wallet's currency as well.
> **The recipient list replaces**
>
> Writing the warning recipients **overwrites** the list: an address you leave out stops getting the warning. Sending only the address you meant to add closes the others. The account owner never enters this list and always gets the warning.
> **Changing automatic payment reaches the open invoices**
>
> Turning the wallet collection of renewals on or off also takes **the renewal invoices open at that moment** down the new road. This is not a setting for the future: the collections waiting are hit at once. Make sure the balance covers them.
> **The backup card steps in when the wallet falls short**
>
> The backup card works after the wallet rather than **in place of** it: the balance is tried first and the card is charged when it falls short. Sending zero clears the chain, and a failed collection can suspend a service. Saving is refused on a card that has expired.
> **The movements are a historical record**
>
> A wallet movement is never removed or corrected: a refund adds **a new row the other way** rather than taking the old one out. Read the balance from the wallet state rather than adding the movements up, since that value is fresh on every call.
### Related Articles
- [Paying an Invoice](https://dev.wisecp.com/en/paying-an-invoice)
- [The Account Behind the Key](https://dev.wisecp.com/en/the-account-of-the-key)
- [The Address Book](https://dev.wisecp.com/en/the-address-book)
## Orders
https://dev.wisecp.com/en/ordering-as-the-client
The four endpoints that show past orders, quote a price and place the order.
### Overview
A customer can order on their own behalf, and that order completes **without a browser**. Payment is kept narrow for that reason: the account balance or a card the account has saved.
The flow runs in three steps: read the schema from the product detail, see the price with the preview, then place the order. The preview runs the **same chain** as the order endpoint and writes nothing.
Taking a domain does not belong here. A new domain is taken from the domain endpoints first and then named in the order as one you **already own**.
### Reference
#### Listing the Orders
get/api/v1/client/orders
`Orders/GetOrders` the key's owner
Returns the account's orders, newest first.
Query 3
pageintWhich page.
limitintRows per page. 100 at the most.
statusstringThe state filter: waiting, in process, active or cancelled.
Response fields data[] — 8 + meta — 4
idintThe order id.
numberstringThe order number the customer sees.
statusstringWhere the order stands.
totalobjectThe order total. It is in the wallet currency.
payment_methodstringThe payment method recorded.
invoice_idintThe order invoice. It comes empty when there is none.
items_countintHow many lines the order holds.
created_atstringThe day it was placed.
total_countintHow many orders there are. It comes back under meta as the total.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 2
status_invalid422The state is not one the orders use.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/orders?status=active' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/orders?status=active', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data, meta } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/orders?status=active');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The listing carries NO LINES: the items and the services born come on the detail endpoint.
$rows = Kernel::internal('client:Orders/GetOrders', ['owner_id' => $uid])['data'];
```
#### Reading an Order in Full
get/api/v1/client/orders/{id}
`Orders/GetOrder` the key's owner
Returns an order's lines, the services born and its invoice.
Response fields data — 12
idintThe order id.
numberstringThe order number.
statusstringWhere the order stands.
totalobjectThe order total.
payment_methodstringThe payment method recorded.
invoice_idintThe order invoice id.
items_countintHow many lines.
created_atstringThe day it was placed.
itemsobject[]The order lines. Each carries a label, a quantity and a line total.
servicesobject[]The services born from the order. Each carries an id, a name, a type and a state, and the id goes to the service endpoint.
invoiceobjectThe order invoice summary. It carries the id, number, state, total and the dates.
notesstringThe note written while ordering.
Errors 2
not_found404No such order, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/orders/918' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/orders/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const ids = data.services.map((s) => s.id);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/orders/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The services can already exist while the order still reads WAITING; follow the service state.
$o = Kernel::internal('client:Orders/GetOrder', ['owner_id' => $uid, 'id' => $id])['data'];
$live = array_filter($o['services'], fn ($s) => $s['status'] === 'active');
```
#### Pricing an Order
post/api/v1/client/orders/preview
`Orders/PreviewOrder` nothing is written
Prices an order body without writing a single row.
Body 4
itemsobject[]req items[]The order lines. One to twenty, in the same shape as the order endpoint.
product_idintreqThe id of the product ordered.
cyclestringreqThe billing cycle. It has to be one the product prices.
quantityintHow many. It counts only where the product allows more than one.
addonsobjectThe add-ons picked. It maps an add-on id to a choice id.
addons_qtyobjectThe count of add-ons priced by quantity.
requirementsobjectThe answers to the product's questions. Every field marked required has to be sent.
requirement_filesobjectThe content for fields wanting a file. It goes as encoded content and an address is refused.
metricsint[]The ids of the meters to switch on.
domainobjectThe line's domain axis. It carries the choice, the name, the subdomain root and the licence fields.
couponsstring[]The coupon codes to try.
billing_profile_idintThe billing profile id. It sets the tax context, and the account default stands in when left out.
paymentobjectThe payment block. Sending it adds the method's fee to the total, and the balance is not checked here.
Response fields data — 6
itemsobject[]The lines priced. Each carries a kind, product, name, cycle, quantity, domain, unit price, set-up fee and line total.
subtotalobjectThe total before discount and tax.
discountobjectThe discount in all.
taxobjectThe tax on the discounted base.
feeobjectThe payment method fee. It is worked out only when the payment block is sent.
totalobjectThe grand total. It is what the order endpoint will charge.
Errors 8
items_required422No line was sent, or there are more than twenty.
product_not_orderable422The product is absent, closed, hidden or its group is shut to orders.
cycle_invalid422The cycle is not one the product prices.
requirement_missing422A required order field was not sent.
domain_acquisition_not_here422Registering or transferring a domain does not happen here.
coupon_invalid422The coupon is invalid or does not apply to these lines.
not_found404The billing profile or card belongs to another account.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/orders/preview' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"items":[{"product_id":55,"cycle":"monthly","quantity":1}],"coupons":["WELCOME10"]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/orders/preview', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ items, coupons }),
});
const { data } = await res.json();
showSummary(data.subtotal, data.discount, data.tax, data.total);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/orders/preview');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['items' => $items]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The preview DOES NOT run the ordering gates: the terms, verification and balance go unchecked here.
$q = Kernel::internal('client:Orders/PreviewOrder', ['owner_id' => $uid, 'items' => $items])['data'];
$due = $q['total']['amount'];
```
#### Placing the Order
post/api/v1/client/orders
`Orders/CreateOrder` the balance or a saved card
Places the order and collects payment in the same call.
Body 7
termsboolreqAccepting the terms. It has to be sent true.
itemsobject[]req items[]The order lines. One to twenty.
product_idintreqThe id of the product ordered.
cyclestringreqThe billing cycle. It has to be one the product prices.
quantityintHow many. It counts only where the product allows more than one.
addonsobjectThe add-ons picked. It maps an add-on id to a choice id.
addons_qtyobjectThe count of add-ons priced by quantity.
requirementsobjectThe answers to the product's questions. Every field marked required has to be sent.
requirement_filesobjectThe content for fields wanting a file. It goes as encoded content and an address is refused.
metricsint[]The ids of the meters to switch on.
domainobjectThe line's domain axis. It carries the choice, the name, the subdomain root and the licence fields.
couponsstring[]The coupon codes. The operator's self-applying coupons join in as well.
billing_profile_idintThe billing profile id.
notesstringThe order note. Anything past a thousand characters is cut.
paymentobject paymentThe payment source. It is required once the total is above zero.
methodstringThe road: the account balance or a saved card.
card_idintThe card to charge. The account's default card is charged when left out.
Response fields 201 — data — 6
order_idintThe new order id.
numberstringThe order number.
statusstringThe state right after collection. It reads waiting until provisioning moves it on.
totalobjectThe order total settled.
paymentobject paymentHow the collection went.
methodstringThe road used: the balance, a card or free.
statusstringWhether it was paid, failed or stands open.
cardobjectThe id and last four digits of the card charged.
transaction_idstringThe provider's transaction reference.
errorstringWhy a failed payment failed.
invoiceobjectThe order invoice summary.
Errors 9
terms_required422The terms were not accepted.
verification_required422The account is waiting on verification.
checkout_blocked422A hook refused the order.
insufficient_balance422The wallet does not cover the total.
no_stored_card422No card was named and the account holds no default.
card_not_chargeable422The card's provider cannot charge without a browser.
payment_method_restricted422The method is closed to this customer or these products.
not_found404The billing profile or card belongs to another account.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/orders' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"terms":true,"items":[{"product_id":55,"cycle":"monthly"}],"payment":{"method":"balance"}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/orders', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
terms: true,
items,
payment: { method: 'balance' },
}),
});
const { data } = await res.json();
if (data.payment.status === 'failed') showPayLater(data.invoice);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/orders');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'terms' => true, 'items' => $items,
'payment' => ['method' => 'balance'],
]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A 201 DOES NOT MEAN PAID: a declined card still leaves the order and its unpaid invoice, so read the payment state.
$o = Kernel::internal('client:Orders/CreateOrder',
['owner_id' => $uid, 'terms' => true, 'items' => $items,
'payment' => ['method' => 'card']])['data'];
if ($o['payment']['status'] !== 'paid') $notify($o['invoice']['invoice_id']);
```
### Pitfalls
> **A successful answer does not mean paid**
>
> The order endpoint answers with success even on a failed collection, **because the order was built**: a declined card leaves the order and its unpaid invoice standing. Read whether it was paid from the payment state in the answer. Only the provider's plain approval counts as paid, and an answer wanting a further step fails here.
> **The preview does not run the ordering gates**
>
> The preview runs the whole pricing chain and skips the **gates that belong to the moment of ordering**: accepting the terms, account verification, the policy hook and whether the balance covers it. A body passing the preview cleanly can still be refused by the order endpoint.
> **Registering a domain is refused here**
>
> A line's domain axis takes a domain you **already own** or a free subdomain alone. Asking to register or transfer is refused with a plain error. The right order is to take it from the domain endpoints first and then name it in the order as owned.
> **A file field takes no address**
>
> An order field wanting a file wants **encoded content**, and giving an address is refused. That is a deliberate security decision: the server never downloads an address a caller hands it. Send the file with the request.
> **A waiting order does not mean the service is absent**
>
> An order reads **waiting** right after collection and stays there until provisioning moves it on. The services can already exist by then. Follow the progress from the **service states** in the detail rather than from the order's own.
> **Every amount is in the wallet currency**
>
> The product prices, the preview total and the order total all come in one currency: the account's **wallet currency**. No conversion is needed to compare them with the balance. The display choice on the profile does not move these figures.
### Related Articles
- [What Is on Sale](https://dev.wisecp.com/en/what-is-on-sale)
- [Paying an Invoice](https://dev.wisecp.com/en/paying-an-invoice)
- [Taking a Domain](https://dev.wisecp.com/en/taking-a-domain)
## Invoices
https://dev.wisecp.com/en/paying-an-invoice
The four endpoints that see, read, pay and discount invoices.
### Overview
An invoice is the account's **record of what is owed**. An order, a renewal and a wallet top-up all raise one, and payment goes through it.
Every invoice carries **two states**: the raw one on the record and the one shown to the customer. The second takes the due date into account, so an unpaid invoice takes a separate value once that date passes.
Payment is kept narrow here as well: the account balance or a saved card. The roads wanting a browser step, a part payment and a transfer notice **stay in the panel**.
### Reference
#### Listing the Invoices
get/api/v1/client/invoices
`Invoices/GetInvoices` urgency order
Returns the account's invoices in order of urgency.
Query 6
pageintWhich page.
limitintRows per page. 100 at the most.
statusstringThe state filter. It takes the customer-facing state vocabulary.
searchstringSearches the invoice number and the first line's description.
sortstringThe sort field: raised, due or amount. Left out, the urgency order stands.
dirstringThe sort direction. It works with the sort field alone.
Response fields data[] — 9 + meta — 4
invoice_idintThe invoice id.
numberstringThe invoice number shown.
statusstringThe raw state.
statestringThe state shown to the customer. It comes from the raw state and the due date, and an open invoice past its date takes a value of its own.
totalobjectThe document total. It is in its own currency.
created_atstringThe day it was raised.
paid_atstringThe day it was paid.
due_datestringThe day it falls due.
first_itemstringThe first line's description. It says quickly what the invoice is for.
total_countintHow many invoices there are. It comes back under meta as the total.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 2
status_invalid422The state is not one that is known.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/invoices?status=overdue' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/invoices?status=overdue', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data, meta } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/invoices?status=overdue');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Two state fields exist: the filter takes the CUSTOMER one, and the raw state does not separate overdue.
$rows = Kernel::internal('client:Invoices/GetInvoices',
['owner_id' => $uid, 'status' => 'overdue'])['data'];
```
#### Reading an Invoice
get/api/v1/client/invoices/{id}
`Invoices/GetInvoice` the moment is kept
Returns an invoice's lines, customer record, summary and payments.
Response fields data — 17
invoice_idintThe invoice id.
numberstringThe invoice number shown.
statusstringThe raw state.
statestringThe state shown to the customer. It comes from the raw state and the due date, and an open invoice past its date takes a value of its own.
totalobjectThe document total. It is in its own currency.
created_atstringThe day it was raised.
paid_atstringThe day it was paid.
due_datestringThe day it falls due.
amount_dueobjectWhat is still open. It reaches zero once closed.
payableboolWhether the payment endpoint takes it.
subscription_lockedboolWhether a subscription is collecting it. Paying by hand is refused when it is.
notesstringThe operator notes on it.
billed_toobjectThe customer record kept on the invoice. It carries the details as they stood when it was raised, even after the profile moves: the kind, name, contact, e-mail, tax number, identity number and address.
custom_fieldsobject[]The extra fields the operator chose to show on the invoice.
itemsobject[] items[]The invoice lines.
item_idintThe line id.
parent_item_idintThe parent line. It fills on an add-on line.
descriptionstringThe line description.
eventstringThe flow that wrote it. It comes empty on a line entered by hand.
service_idintThe service billed.
cyclestringThe billing cycle.
period_startstringThe start of the period covered. It can be empty on an older document.
period_endstringThe end of the period covered.
domainstringThe domain the line concerns.
quantityintHow many.
unit_priceobjectThe unit amount.
totalobjectThe line total.
summaryobject summaryThe money summary.
subtotalobjectThe line subtotal.
discountsobjectThe discounts. It carries the dealer discount and any coupon applied.
taxobjectThe tax line. It carries a rate and an amount.
payment_feeobjectThe fee of the method picked.
installmentobjectThe instalment plan. It carries the count and the surcharge.
totalobjectThe document total.
paidobjectWhat has been paid so far.
amount_dueobjectWhat is still open.
transactionsobject[]The money movements that closed. Each carries a kind, a method, the provider reference, an amount and a date, and failed attempts are not kept.
bank_transferobjectA transfer notice waiting for approval. It carries the bank name, the sender and a reference.
Errors 2
not_found404No such invoice, it belongs to another customer, or it is a draft.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/invoices/1193' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/invoices/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.payable && ! data.subscription_locked) enablePayButton();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/invoices/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The customer record on an invoice is a snapshot of THE MOMENT it was raised; do not reconcile it with the profile today.
$inv = Kernel::internal('client:Invoices/GetInvoice', ['owner_id' => $uid, 'id' => $id])['data'];
$thenAddress = $inv['billed_to']['address'];
```
#### Paying an Invoice
post/api/v1/client/invoices/{id}/pay
`Invoices/PayInvoice` the balance or a saved card
Closes an open invoice with the balance or a saved card.
Body 1
paymentobjectreq paymentThe payment source.
methodstringreqThe road: the account balance or a saved card.
card_idintThe card to charge. The account's default card is charged when left out.
Response fields data — 2
invoiceobjectThe invoice read afresh. It carries the number, state, total, what is open and the dates.
paymentobject paymentHow the charge went.
methodstringThe road used.
statusstringWhether it paid or failed. A failure happens on a declined card alone.
cardobjectThe id and last four digits of the card charged.
transaction_idstringThe provider's transaction reference.
errorstringWhy it was declined.
Errors 10
not_found404No such invoice, it belongs to another customer, or it is a draft.
invoice_not_payable422The invoice is not open or nothing is left to pay.
subscription_collects422A subscription is collecting this invoice.
payment_method_invalid422The payment road is neither of the two values.
balance_not_allowed422A top-up invoice cannot be paid from the wallet.
insufficient_balance422The wallet does not cover the amount with the fee. What is needed and what is there come in the answer's detail.
no_stored_card422No card was named and there is no default.
card_expired422The saved card has expired.
card_not_chargeable422The card's provider wants a browser step.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/invoices/1193/pay' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"payment":{"method":"balance"}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/invoices/${id}/pay`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ payment: { method: 'card' } }),
});
const { data } = await res.json();
if (data.payment.status === 'failed') showError(data.payment.error);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/invoices/' . $id . '/pay');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['payment' => ['method' => 'balance']]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A DECLINED CARD is not an error: the answer succeeds, the invoice stays open with its fee, so read the state.
$r = Kernel::internal('client:Invoices/PayInvoice',
['owner_id' => $uid, 'id' => $id, 'payment' => ['method' => 'card']])['data'];
if ($r['payment']['status'] === 'failed') $retryLater($id);
```
#### Applying a Coupon to an Invoice
post/api/v1/client/invoices/{id}/coupon
`Invoices/ApplyInvoiceCoupon` one coupon per document
Applies a coupon to an open invoice and prices the document again.
Body 1
codestringreqThe coupon code.
Response fields data — 3
invoiceobjectThe document priced again.
couponobjectThe coupon applied.
discountobjectThe discount granted on this document.
Errors 8
not_found404No such invoice, it belongs to another customer, or it is a draft.
invoice_not_payable422The invoice is not open.
coupon_code_required422No code was sent.
coupon_invalid422No such coupon.
coupon_not_invoice422The coupon cannot be used on invoices.
coupon_used422A coupon was already applied to this document.
coupon_scope422The coupon does not apply to the lines on this invoice.
coupon_rejected422The coupon engine refused it. The reason comes in the message.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/invoices/1193/coupon' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"code":"WELCOME10"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/invoices/${id}/coupon`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ code }),
});
const { data } = await res.json();
showNewTotal(data.invoice.total, data.discount);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/invoices/' . $id . '/coupon');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['code' => $code]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Apply the coupon BEFORE paying: a closed document cannot be changed and there is no way back.
Kernel::internal('client:Invoices/ApplyInvoiceCoupon',
['owner_id' => $uid, 'id' => $id, 'code' => $code]);
Kernel::internal('client:Invoices/PayInvoice',
['owner_id' => $uid, 'id' => $id, 'payment' => ['method' => 'balance']]);
```
### Pitfalls
> **A declined card returns no error**
>
> The payment endpoint answers **successfully** on a declined card as well: the invoice stays open and the fee of the method picked stays on the document. Read the outcome from the payment state in the answer. Take that fee into account when paying the same invoice another way.
> **A subscription collecting it refuses a manual payment**
>
> Where a payment provider subscription collects an invoice the payment endpoint **refuses**. That is a gate against a double charge rather than a fault. Read the subscription field in the detail and close the pay button; paying by hand wants the subscription cancelled first.
> **The customer details on an invoice belong to the moment**
>
> An invoice **keeps the customer record on itself**: the address, tax number and title stand as they were when it was raised. The document does not move when the profile does, because it is a legal record. Do not report a mismatch by comparing it with the profile today.
> **One coupon per document, and before paying**
>
> One invoice takes **one coupon**, and only while the document is open. Applying one after payment is refused and there is no way back. Try the coupon before the payment call.
> **A top-up invoice is not paid from the wallet**
>
> The invoice raised to put money into the wallet **cannot be paid from the wallet**, since that would be circular. It is paid with a saved card or from the panel. Handle that error apart when writing a general payment flow.
> **The two state fields do not say the same thing**
>
> The raw state is the value on the record while the customer-facing one **takes the due date in**. Only the second moves when an unpaid invoice passes its date. The filter takes the customer state, so the overdue ones cannot be found by the raw one.
### Related Articles
- [The Account Balance](https://dev.wisecp.com/en/the-account-balance)
- [Ordering as the Client](https://dev.wisecp.com/en/ordering-as-the-client)
- [The Services You Own](https://dev.wisecp.com/en/the-services-you-own)
## Tickets
https://dev.wisecp.com/en/asking-for-support
The eleven endpoints that open, answer, close and rate a support ticket.
### Overview
A support ticket is a **conversation**: the customer opens it, the staff reply, and it closes. Eleven endpoints cover every step of it.
Two dictionaries want reading before a ticket is opened: which fields each **department** asks for, and which **access groups** take encrypted details.
A password does not belong in the message body. A separate field exists for the access groups, and a password-type value there is stored **encrypted**.
### Reference
#### Listing the Departments
get/api/v1/client/tickets/departments
`Tickets/GetTicketDepartments` the opening schema
Returns the departments a ticket can open in, each with its own field schema.
Response fields data[] — 4
idintThe department id.
namestringThe department name.
descriptionstringWhat it is for.
custom_fieldsobject[] custom_fields[]The fields asked at opening.
idintThe field id. It is the key of the map in the body.
namestringThe field label.
typestringThe input type.
requiredboolWhether it may be left empty.
optionsobject[]The choices on a picker field. Each carries a value and a label, and the value is what goes.
Errors 2
ticket_system_disabled422The operator closed the support system.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/tickets/departments' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/tickets/departments', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
renderDepartmentForm(data[0].custom_fields);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/departments');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The field schema differs PER DEPARTMENT: build the form from the chosen one's schema.
$deps = Kernel::internal('client:Tickets/GetTicketDepartments', ['owner_id' => $uid])['data'];
$schema = array_column($deps, 'custom_fields', 'id')[$did] ?? [];
```
#### Listing the Access Groups
get/api/v1/client/tickets/access-groups
`Tickets/GetTicketAccessGroups` encrypted fields
Returns the access detail groups a message can carry, with their schemas.
Response fields data[] — 3
idintThe group id. This is what goes into the group field of an access row.
namestringThe group name.
custom_fieldsobject[] custom_fields[]The group's access fields.
idintThe field id. It is the key of the map in the body.
namestringThe field label.
typestringThe input type.
requiredboolWhether it may be left empty.
optionsobject[]The choices on a picker field. Each carries a value and a label, and the value is what goes.
Errors 2
ticket_system_disabled422The operator closed the support system.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/tickets/access-groups' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/tickets/access-groups', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const server = data.find((g) => g.name.includes('Server'));
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/access-groups');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A password-type field is stored ENCRYPTED; use this rather than writing secrets into the message body.
$groups = Kernel::internal('client:Tickets/GetTicketAccessGroups', ['owner_id' => $uid])['data'];
$creds = [['group_id' => $groups[0]['id'], 'fields' => $values]];
```
#### Listing the Tickets
get/api/v1/client/tickets
`Tickets/GetTickets` state order
Returns the account's support tickets in order of state.
Query 5
pageintWhich page.
limitintRows per page. 100 at the most.
statusstringThe state filter. It takes the customer-facing vocabulary.
departmentintThe department filter.
searchstringSearches the subject, the reference and the department name.
Response fields data[] — 11 + meta — 4
ticket_idintThe ticket id.
refstringThe reference the customer quotes.
subjectstringThe subject.
statusstringThe raw state.
statestringThe state shown to the customer.
priorityintThe priority. One to four: low, medium, high, urgent.
departmentobjectThe department. It carries an id and a name.
ratingintThe rating given to the ticket.
created_atstringWhen it was opened.
unreadboolWhether an unread staff reply waits.
last_replyobjectThe last visible message. It carries when and who wrote it.
totalintHow many tickets there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 3
ticket_system_disabled422The operator closed the support system.
status_invalid422The state is not one that is known.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/tickets?status=answered' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/tickets?status=answered', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const waiting = data.filter((t) => t.unread);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets?status=answered');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The unread mark shows in the LISTING alone: reading the detail clears it, so count from the list first.
$rows = Kernel::internal('client:Tickets/GetTickets', ['owner_id' => $uid])['data'];
$badge = count(array_filter($rows, fn ($t) => $t['unread']));
```
#### Opening a Ticket
post/api/v1/client/tickets
`Tickets/CreateTicket` it takes attachments
Opens a new support ticket.
Body 9
department_idintreqThe department id.
subjectstringreqThe subject.
messagestringreqThe opening message. Five characters at the least, in plain text with markup stripped.
priorityintThe priority. Medium stands in when left out.
service_idintTies the ticket to a service.
custom_fieldsobjectThe answers to the department fields. It maps a field id to a value, and a tick field takes a list.
credentialsobject[]The access details. Each row carries a group id and a field map, and it is written into the message encrypted.
attachmentsarrayThe attachments. They go as encoded content and an address is refused.
encrypt_messageboolWhether the message body is stored encrypted.
Response fields 201 — data — 13
dataobjectThe ticket opened, in full. Same shape as the read endpoint.
Errors 10
not_found404The service to tie it to is not this account's.
ticket_system_disabled422The operator closed the support system.
subject_required422The subject is empty.
department_invalid422The department is unknown or closed.
message_too_short422The message is under five characters.
custom_field_required422A required department field is empty. Which one comes in the answer's detail.
access_group_invalid422An access row carries an unknown group.
credential_field_required422A required access field is empty.
attachment_invalid422An attachment came as an address or failed validation.
ticket_rejected422A hook refused the ticket.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/tickets' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"department_id":4,"subject":"Cannot reach my server","message":"SSH times out since this morning.","priority":3}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/tickets', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
department_id: 4,
subject,
message,
credentials: [{ group_id: 1, fields: { 30: ip, 32: password } }],
}),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($ticket),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The attachments are checked BEFORE the ticket is saved: a broken file leaves no half ticket.
Kernel::internal('client:Tickets/CreateTicket', ['owner_id' => $uid] + $ticket);
```
#### Reading a Ticket and Its Messages
get/api/v1/client/tickets/{id}
`Tickets/GetTicket` it marks as read
Returns a ticket's heading and the whole run of messages.
Response fields data — 13
ticket_idintThe ticket id.
refstringThe reference the customer quotes.
subjectstringThe subject.
statusstringThe raw state.
statestringThe state shown to the customer.
priorityintThe priority. One to four: low, medium, high, urgent.
departmentobjectThe department. It carries an id and a name.
ratingintThe rating given to the ticket.
created_atstringWhen it was opened.
lockedboolWhether the staff locked it. Replying and reopening stop while it is.
can_replyboolWhether a reply can be written.
related_serviceobjectThe service tied to it. It carries an id, a name, a type and a state.
last_reply_atstringWhen the last message came.
messagesobject[] messages[]The visible messages, oldest first. The staff's internal notes never appear.
message_idintThe message id. This is the number given when rating a staff reply.
authorobjectWho wrote it. It carries a kind and a name.
is_htmlboolWhether the body carries markup. It can be true on a staff message.
bodystringThe message itself.
created_atstringWhen it was written.
ratingintThe rating given to this reply. It fills on a staff message alone.
attachmentsobject[]The attachments. Each carries an id, a name and a size, and the content comes from the download endpoint.
credentialsobject[]The access details unlocked. It carries the group and its fields, and a password-type value is marked secret.
Errors 3
not_found404No such ticket, or it belongs to another customer.
ticket_system_disabled422The operator closed the support system.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/tickets/429' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/tickets/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
renderThread(data.messages, data.can_reply);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This read MARKS AS READ: a job counting badges drops the badge the moment it calls.
$t = Kernel::internal('client:Tickets/GetTicket', ['owner_id' => $uid, 'id' => $id])['data'];
$html = array_filter($t['messages'], fn ($m) => $m['is_html']);
```
#### Writing a Reply
post/api/v1/client/tickets/{id}/reply
`Tickets/ReplyTicket` it takes attachments
Adds a reply to an open ticket.
Body 4
messagestringreqThe reply text. Five characters at the least.
credentialsobject[]The access details.
attachmentsarrayThe attachments.
encrypt_messageboolWhether the body is stored encrypted.
Response fields data — 2
ticketobjectThe ticket's new state. A reply moves it back to waiting.
messageobjectThe reply saved. It comes in the shape used in the message run.
Errors 7
not_found404No such ticket, or it belongs to another customer.
ticket_system_disabled422The operator closed the support system.
ticket_not_open422The ticket is closed or locked.
message_too_short422The message is under five characters.
access_group_invalid422The access rows did not pass the schema.
attachment_invalid422An attachment was refused.
reply_rejected422A hook refused the reply.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/tickets/429/reply' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"message":"The firewall rule is back, thank you."}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/tickets/${id}/reply`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ message }),
});
const { data } = await res.json();
appendMessage(data.message);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/' . $id . '/reply');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['message' => $text]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A reply moves the ticket back to WAITING: a closed one takes none, so reopen it first.
$t = Kernel::internal('client:Tickets/GetTicket', ['owner_id' => $uid, 'id' => $id])['data'];
if (! $t['can_reply']) Kernel::internal('client:Tickets/ReopenTicket', ['owner_id' => $uid, 'id' => $id]);
```
#### Closing a Ticket
post/api/v1/client/tickets/{id}/close
`Tickets/CloseTicket` a rating may come with it
Closes a ticket as solved.
Body 1
ratingintA rating given while closing. It counts only while the ticket carries none.
Response fields data — 3
ticket_idintThe ticket id.
statusstringThe new raw state.
statestringThe new state shown.
Errors 3
not_found404No such ticket, or it belongs to another customer.
ticket_system_disabled422The operator closed the support system.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/tickets/429/close' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"rating":5}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/tickets/${id}/close`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ rating: 5 }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/' . $id . '/close');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['rating' => 5]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Rating while closing is a ONE-TIME chance: a ticket that already carries one skips the value quietly.
Kernel::internal('client:Tickets/CloseTicket', ['owner_id' => $uid, 'id' => $id, 'rating' => 5]);
```
#### Reopening a Ticket
post/api/v1/client/tickets/{id}/reopen
`Tickets/ReopenTicket` not while locked
Reopens a closed ticket.
Body —
——No body is needed. The id in the path names the ticket; send an empty body.
Response fields data — 3
ticket_idintThe ticket id.
statusstringThe new raw state.
statestringThe new state shown.
Errors 4
not_found404No such ticket, or it belongs to another customer.
ticket_system_disabled422The operator closed the support system.
ticket_locked422The staff locked the ticket.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/tickets/429/reopen' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/tickets/${id}/reopen`, {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/' . $id . '/reopen');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A LOCKED ticket cannot be reopened: opening a new one is the only road there.
$t = Kernel::internal('client:Tickets/GetTicket', ['owner_id' => $uid, 'id' => $id])['data'];
if ($t['locked']) $openNewTicket();
```
#### Rating a Ticket
post/api/v1/client/tickets/{id}/rating
`Tickets/RateTicket` once only
Gives the ticket a rating from one to five.
Body 1
ratingintreqThe rating given. One to five.
Response fields data — 2
ticket_idintThe ticket id.
ratingintThe rating written.
Errors 5
not_found404No such ticket, or it belongs to another customer.
ticket_system_disabled422The operator closed the support system.
rating_invalid422The rating is not between one and five.
already_rated422The ticket already carries a rating. It cannot be changed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/tickets/429/rating' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"rating":5}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/tickets/${id}/rating`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ rating }),
});
if (res.status === 422) hideRatingWidget();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/' . $id . '/rating');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['rating' => $n]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A rating is FINAL: once given it cannot be changed, so ask for confirmation in your interface.
$t = Kernel::internal('client:Tickets/GetTicket', ['owner_id' => $uid, 'id' => $id])['data'];
if ($t['rating'] === null) Kernel::internal('client:Tickets/RateTicket',
['owner_id' => $uid, 'id' => $id, 'rating' => $n]);
```
#### Rating a Staff Reply
post/api/v1/client/tickets/{id}/replies/{rid}/rating
`Tickets/RateTicketReply` once only
Rates one staff reply on its own.
Body 1
ratingintreqThe rating given. One to five.
Response fields data — 2
message_idintThe reply rated.
ratingintThe rating written.
Errors 5
not_found404No such ticket, or the id given is not a visible staff reply.
ticket_system_disabled422The operator closed the support system.
rating_invalid422The rating is not between one and five.
already_rated422The reply already carries a rating.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/tickets/429/replies/878/rating' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"rating":4}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/tickets/${id}/replies/${rid}/rating`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ rating }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/' . $id . '/replies/' . $rid . '/rating');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['rating' => $n]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// STAFF replies alone can be rated: the id of your own message answers not found.
$t = Kernel::internal('client:Tickets/GetTicket', ['owner_id' => $uid, 'id' => $id])['data'];
$staff = array_filter($t['messages'], fn ($m) => $m['author']['kind'] === 'staff');
```
#### Downloading an Attachment
get/api/v1/client/tickets/{id}/attachments/{aid}
`Tickets/GetTicketAttachment` encoded content
Returns a message attachment together with its content.
Response fields data — 6
attachment_idintThe attachment id.
message_idintThe message it hangs from. It can come empty on an older opening record.
namestringThe original file name.
sizeintThe file size.
mimestringThe type worked out from the extension. It falls back to a general value on an unknown one.
contentstringThe file itself. It comes encoded.
Errors 3
not_found404No such ticket or attachment, it is not yours, or it hangs from a hidden note.
ticket_system_disabled422The operator closed the support system.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/tickets/429/attachments/55' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/tickets/${id}/attachments/${aid}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const blob = await (await fetch(`data:${data.mime};base64,${data.content}`)).blob();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/tickets/' . $id . '/attachments/' . $aid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The content comes ENCODED inside the JSON: account for the memory on a large file.
$a = Kernel::internal('client:Tickets/GetTicketAttachment',
['owner_id' => $uid, 'id' => $id, 'aid' => $aid])['data'];
file_put_contents($a['name'], base64_decode($a['content']));
```
### Pitfalls
> **Reading the detail clears the unread mark**
>
> Reading a ticket's detail **clears the unread mark** on the account. A job building a notification badge drops it before the customer ever sees it. Count from the listing and call the detail only when the customer truly opens it.
> **A locked ticket cannot be reopened**
>
> Where the staff locked a ticket neither a reply nor a reopen works. That is **different** from being closed: a closed ticket reopens and a locked one does not. Read the lock field in the detail and offer opening a new ticket instead.
> **A rating is final and cannot be taken back**
>
> Both a ticket rating and a staff reply rating are given **once**, and a second attempt is refused. Sending a rating while closing spends the same right, and a ticket that already carries one skips the value quietly. Ask for confirmation in your interface.
> **Secrets go in the access field and not the message body**
>
> A separate structure exists for a password or a key: the access group rows. A password-type value there is stored **encrypted** and unlocked for the owner and the staff alone. Writing the same detail into the message text leaves it in plain sight.
> **An attachment cannot be sent as an address**
>
> Attachments go as **encoded content** and giving an address is refused. They are checked before the ticket is saved, so a broken file leaves no half ticket. Downloading works the same way: the content comes encoded inside the JSON.
> **Internal notes never appear**
>
> The notes the staff write among themselves **never appear** in the message run, and the attachments on them cannot be downloaded. A gap in the message ids on the customer side is the design rather than a fault.
### Related Articles
- [The Services You Own](https://dev.wisecp.com/en/the-services-you-own)
- [Client API First Calls](https://dev.wisecp.com/en/client-api-first-calls)
## SMS
https://dev.wisecp.com/en/sending-messages
The five endpoints that price a bulk send, make it and show its history.
### Overview
A customer can send messages in bulk, paying from their own wallet. The flow runs in three steps: pick a **sender name**, get a price, send.
The price follows the destination country and the message's **part count**. A longer text, or one leaving the basic alphabet, raises the part count and the amount grows with it.
Some countries want the sender name **registered beforehand**. Numbers going to a country without that registration do not drop quietly: they appear in the skipped list with the reason.
### Reference
#### Listing the Sender Names
get/api/v1/client/sms/senders
`Sms/GetSmsSenders` the key's owner
Returns the sender names a send can use, along with their country registrations.
Response fields data[] — 4
idintThe sender id.
namestringThe text the recipient sees. This is what the send endpoint takes.
is_defaultboolWhether it is the account's default.
countriesobject[]Where it stands in the countries wanting pre-registration. Each carries a country code and a state, and the countries wanting none never appear.
Errors 3
sms_disabled422The operator closed the international message service.
sms_api_disabled422The operator closed the message interface. The panel keeps working.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/sms/senders' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/sms/senders', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const preferred = data.find((s) => s.is_default) ?? data[0];
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/sms/senders');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// An empty country list is NO BAR: most countries want no pre-registration and the name works there straight away.
$senders = Kernel::internal('client:Sms/GetSmsSenders', ['owner_id' => $uid])['data'];
$name = $senders[0]['name'] ?? null;
```
#### Getting a Quote
post/api/v1/client/sms/quote
`Sms/QuoteSms` nothing is sent
Says what a send will cost and what will be left out.
Body 3
senderstringreqThe sender name. It has to be one of the account's live names.
messagestringreqThe message text. Text past the part ceiling is cut and the cut is reported.
numbersarrayreqThe recipient numbers. In international form, and one string is split on lines, commas and semicolons.
Response fields data — 6
messageobjectThe text analysis. The encoding, the length, how many parts, whether it was cut and the text that will truly go.
recipientsintHow many numbers will be charged and sent.
total_partsintThe parts in all. This is the billing unit.
totalobjectWhat the send endpoint will take.
countriesobject[]The breakdown per destination. A code, a name, a count, the parts, the unit price and the total.
skippedobjectWhat was left out. A count, the entries that could not be read, the countries with no price and the countries where the sender is not registered.
Errors 6
sms_disabled422The operator closed the international message service.
sms_api_disabled422The operator closed the message interface. The panel keeps working.
sender_invalid422The sender is missing, not yours or not live.
message_required422The message is empty.
numbers_required422The recipient list is empty.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/sms/quote' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"sender":"TESTBRAND","message":"Your code is 482913","numbers":["+15551112233"]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/sms/quote', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ sender, message, numbers }),
});
const { data } = await res.json();
if (data.skipped.total) reviewSkipped(data.skipped);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/sms/quote');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(compact('sender', 'message', 'numbers')),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A dropped destination is NO ERROR: the quote always succeeds and the loss is read from the skipped block.
$q = Kernel::internal('client:Sms/QuoteSms',
['owner_id' => $uid, 'sender' => $sender, 'message' => $text, 'numbers' => $nums])['data'];
$willCost = $q['total']['amount'];
$willDrop = $q['skipped']['total'];
```
#### Sending in Bulk
post/api/v1/client/sms/send
`Sms/SendSms` it takes from the wallet
Sends the message and takes the amount from the wallet.
Body 3
senderstringreqThe sender name. It has to be one of the account's live names.
messagestringreqThe message text. Text past the part ceiling is cut and the cut is reported.
numbersarrayreqThe recipient numbers. In international form, and one string is split on lines, commas and semicolons.
Response fields 201 — data — 9
message_idintThe send id. The history endpoint is asked with it.
senderstringThe sender used.
acceptedintHow many recipients were charged and handed to the provider.
partsintThe parts per message.
total_partsintThe parts in all.
totalobjectWhat was taken from the wallet.
balanceobjectThe wallet after the charge.
report_idstringThe provider's batch reference.
skippedobjectWhat was left out. A count, the entries that could not be read, the countries with no price and the countries where the sender is not registered.
Errors 10
sms_disabled422The operator closed the international message service.
sms_api_disabled422The operator closed the message interface. The panel keeps working.
sender_invalid422The sender is missing, not yours or not live.
no_recipients422Every number was left out. The reason comes in the answer's detail.
price_unavailable422The amount priced to zero.
send_rejected422A hook refused the send.
sms_module_unavailable422No sending provider is configured.
insufficient_balance422The wallet does not cover it. Nothing is sent and nothing is taken.
send_failed500The provider refused the send. The whole charge is returned.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/sms/send' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"sender":"TESTBRAND","message":"Your code is 482913","numbers":["+15551112233"]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/sms/send', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ sender, message, numbers }),
});
const { data } = await res.json();
console.log(data.accepted, data.total, data.balance);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/sms/send');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(compact('sender', 'message', 'numbers')),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The SERVER prices it again: the figure in the quote is no promise and the send knows its own price.
$r = Kernel::internal('client:Sms/SendSms',
['owner_id' => $uid, 'sender' => $sender, 'message' => $text, 'numbers' => $nums])['data'];
$charged = $r['total']['amount'];
```
#### The Sending History
get/api/v1/client/sms/messages
`Sms/GetSmsMessages` the key's owner
Returns the sends made, newest first.
Query 2
pageintWhich page.
limitintRows per page. 100 at the most.
Response fields data[] — 9 + meta — 4
message_idintThe send id.
senderstringThe sender used.
textstringThe text sent.
recipientsintHow many recipients were charged.
partsintThe parts per message.
total_partsintThe parts in all.
totalobjectWhat was taken.
countriesobject[]The breakdown per destination.
created_atstringWhen it was sent.
total_countintHow many sends there are. It comes back under meta as the total.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 3
sms_disabled422The operator closed the international message service.
sms_api_disabled422The operator closed the message interface. The panel keeps working.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/sms/messages' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/sms/messages', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data, meta } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/sms/messages');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The history holds NO RECIPIENT NUMBERS: they come on the single-send endpoint alone.
$rows = Kernel::internal('client:Sms/GetSmsMessages', ['owner_id' => $uid])['data'];
$one = Kernel::internal('client:Sms/GetSmsMessage',
['owner_id' => $uid, 'id' => $rows[0]['message_id']])['data'];
```
#### Reading One Send
get/api/v1/client/sms/messages/{id}
`Sms/GetSmsMessage` the key's owner
Returns one send together with its recipient numbers.
Response fields data — 11
dataobjectThe fields of a history row.
numbersstring[]The numbers charged and sent.
report_idstringThe provider's batch reference.
Errors 4
not_found404No such send, or it belongs to another customer.
sms_disabled422The operator closed the international message service.
sms_api_disabled422The operator closed the message interface. The panel keeps working.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/sms/messages/4520' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/sms/messages/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
console.log(data.numbers.length, data.report_id);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/sms/messages/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A per-recipient DELIVERY REPORT is ABSENT here: the live provider report stays in the panel view.
$m = Kernel::internal('client:Sms/GetSmsMessage', ['owner_id' => $uid, 'id' => $id])['data'];
$sentTo = $m['numbers'];
```
### Pitfalls
> **Dropped recipients return no error**
>
> The quote and send endpoints do not drop invalid numbers, unpriced countries and countries where the sender is unregistered **in silence**, and they do not stop the send either: the rest goes and the dropped ones are listed in the answer. Without reading that block you never notice part of the message never left.
> **The quote is not a promise**
>
> The send endpoint **prices it again itself** and never trusts a figure the caller sends. A price or a sender registration moving between the quote and the send can change what is taken. Read the settled figure from the send answer.
> **The charge is atomic and the refund is whole**
>
> The wallet is charged with **one conditional update**: two sends at once cannot push the balance below zero. Where the provider refuses, the whole charge comes back and no message leaves. A failed send costs nothing.
> **Leaving the basic alphabet raises the part count**
>
> A message in the basic alphabet fits more characters per part, while a single letter outside it drops the text into **the other encoding** and the capacity per part falls by more than half. The amount rests on parts, so the cost jumps. Read the encoding field in the quote.
> **The history carries no numbers**
>
> The sending history gives summary rows and the **recipient numbers** come only when you read one send. A per-recipient delivery report is absent from the API entirely and stays in the panel, since it is pulled live from the provider.
### Related Articles
- [The Account Balance](https://dev.wisecp.com/en/the-account-balance)
- [Client API First Calls](https://dev.wisecp.com/en/client-api-first-calls)
## Affiliate
https://dev.wisecp.com/en/your-affiliate-earnings
The five endpoints managing a partner's programme, earnings and payout requests.
### Overview
The affiliate programme is where a customer takes a share of the business their own link brings in. These five endpoints manage **one partner's own** programme.
Earnings move in two stages: a commission **clears** first and then reaches the available balance. A payout is asked from the available amount alone.
Payouts are settled by hand. A request is opened, the operator approves it, and only one request stands open at a time.
### Reference
#### Reading Where You Stand
get/api/v1/client/affiliate
`Affiliate/GetAffiliate` it moves what cleared
Returns the programme, the earnings and the payout state in one call.
Response fields data — 7
enrolledboolWhether the account joined.
disabledboolWhether the operator closed this partnership.
programobjectThe programme rules. The commission rate, the tracking window, the clearing period and the payout floor.
referralobjectThe referral to share. It carries a code and a full link.
balanceobject balanceThe earnings block.
availableobjectWhat can be asked for now.
clearingobjectWhat is waiting to clear.
earnedobjectWhat has been earned in all.
paid_outobjectWhat has been paid out.
statsobjectThe referral counts. Those who signed up and those who earned commission.
payoutobject payoutWhere payout stands.
readyboolWhether what is available reaches the floor.
pending_requestobjectThe one request waiting. It carries an amount, a method, a state and when it was asked.
gatewaysstring[]The payout roads the operator offers.
saved_destinationsobjectYour saved destination per road.
Errors 2
affiliate_disabled422The operator closed the affiliate programme.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/affiliate' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/affiliate', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (! data.enrolled) showJoinButton(data.program);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/affiliate');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This read WRITES: it moves the cleared commissions into the available balance and is not read-only.
$aff = Kernel::internal('client:Affiliate/GetAffiliate', ['owner_id' => $uid])['data'];
$canAsk = $aff['payout']['ready'] ?? false;
```
#### Joining the Programme
post/api/v1/client/affiliate/enroll
`Affiliate/EnrollAffiliate` the account currency
Signs the account up to the affiliate programme.
Body —
——No body is needed.
Response fields 201 — data — 7
dataobjectThe new partnership dashboard. Same shape as the read endpoint.
Errors 2
affiliate_disabled422The operator closed the affiliate programme.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/affiliate/enroll' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/affiliate/enroll', {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
shareLink(data.referral.link);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/affiliate/enroll');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The partnership opens in THE ACCOUNT's currency and cannot be changed later; check the profile first.
$me = Kernel::internal('client:Account/GetMe', ['owner_id' => $uid])['data'];
if ($me['currency'] === $wanted)
Kernel::internal('client:Affiliate/EnrollAffiliate', ['owner_id' => $uid]);
```
#### Listing the Commissions
get/api/v1/client/affiliate/commissions
`Affiliate/GetAffiliateCommissions` the key's owner
Returns the commissions earned, newest first.
Query 2
pageintWhich page.
limitintRows per page. 100 at the most.
Response fields data[] — 10 + meta — 4
commission_idintThe record id.
statusstringThe raw state.
statestringThe state shown: available, clearing or refused.
referralstringThe display name of the customer referred.
servicestringThe service the commission came from.
service_typestringThe service's product type.
order_amountobjectThe amount of the order referred.
commissionobjectYour share of it.
created_atstringWhen the record was written.
clearing_datestringThe day it becomes available.
totalintHow many records there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 3
affiliate_disabled422The operator closed the affiliate programme.
not_enrolled422The account has not joined the programme.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/affiliate/commissions' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/affiliate/commissions', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const soon = data.filter((c) => c.state === 'clearing');
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/affiliate/commissions');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A clearing commission CANNOT be paid yet: it reaches the available balance on its clearing day.
$rows = Kernel::internal('client:Affiliate/GetAffiliateCommissions', ['owner_id' => $uid])['data'];
$soon = array_filter($rows, fn ($c) => $c['state'] === 'clearing');
```
#### Asking to Be Paid
post/api/v1/client/affiliate/withdraw
`Affiliate/WithdrawAffiliate` one request at a time
Asks for the available earnings to be paid out.
Body 4
amountfloatreqThe amount asked for. It has to sit between the floor and what is available.
gatewaystringreqThe payout road. It has to be one the operator offers.
gateway_infostringThe destination detail. It can be left out where one is saved.
save_defaultboolKeep this destination for later requests.
Response fields 201 — data — 4
withdrawal_idintThe request id.
amountobjectThe amount asked for.
gatewaystringThe road picked.
statusstringWhere the request stands. The operator settles it by hand.
Errors 10
affiliate_disabled422The operator closed the affiliate programme.
not_enrolled422The account has not joined the programme.
affiliate_disabled_account422The operator closed this partnership.
withdrawal_pending422A request is already waiting.
below_minimum422What is available does not reach the floor.
amount_invalid422The amount sits outside the range allowed. Both bounds come in the answer's detail.
gateway_invalid422The road is none of the operator's.
gateway_info_required422No destination was given and none is saved.
withdrawal_rejected422A hook refused the request.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/affiliate/withdraw' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"amount":40,"gateway":"PayPal","gateway_info":"partner@example.com"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/affiliate/withdraw', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ amount, gateway, save_default: true }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/affiliate/withdraw');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['amount' => 40, 'gateway' => 'PayPal']),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Take the amount FROM THE DASHBOARD: what is available can move as commissions clear during the read.
$aff = Kernel::internal('client:Affiliate/GetAffiliate', ['owner_id' => $uid])['data'];
$max = $aff['balance']['available']['amount'];
Kernel::internal('client:Affiliate/WithdrawAffiliate',
['owner_id' => $uid, 'amount' => $max, 'gateway' => $gw]);
```
#### Saving a Payout Destination
put/api/v1/client/affiliate/payment-method
`Affiliate/SaveAffiliatePayoutMethod` the key's owner
Saves or clears the destination detail of a payout road.
Body 2
gatewaystringreqThe payout road.
infostringThe destination detail. Sending it empty clears the record.
Response fields data — 1
saved_destinationsobjectThe destination map as it now stands. It carries the detail saved per road.
Errors 4
affiliate_disabled422The operator closed the affiliate programme.
not_enrolled422The account has not joined the programme.
gateway_invalid422The road is none of the operator's.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/affiliate/payment-method' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"gateway":"PayPal","info":"partner@example.com"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/affiliate/payment-method', {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ gateway, info }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/affiliate/payment-method');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['gateway' => $gw, 'info' => $info]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A destination is kept PER ROAD: clearing one leaves the others alone and the map is managed one by one.
Kernel::internal('client:Affiliate/SaveAffiliatePayoutMethod',
['owner_id' => $uid, 'gateway' => $gw, 'info' => '']);
```
### Pitfalls
> **Reading the dashboard actually writes**
>
> Reading where you stand **moves the commissions** whose clearing day arrived into the available balance. The endpoint is not read-only, and two calls in a row can show different balances. Call it right before a payout request to see the highest amount you may ask for.
> **A clearing commission is not money yet**
>
> A commission is not paid the moment it is earned: it waits out the **clearing period** the operator set. The clearing figure on the dashboard is part of what was earned and cannot be asked for. Adding the two figures and asking for the sum is refused.
> **One payout request at a time**
>
> A second request **cannot be opened** while one waits. A new one is refused until the operator settles it by hand. Read the pending field on the dashboard and close the request road in your interface, or the customer meets an error they cannot place.
> **The partnership opens in the account currency**
>
> The partnership record opens in the account's currency at the time of joining and the commissions build up in it. Changing the currency on the profile later **does not move the earnings**. Make sure the currency is right before joining.
> **The destination is kept per road**
>
> Every payout road keeps **a destination of its own**, and clearing one leaves the others alone. Leaving the destination out of a request falls back to that road's saved detail, and the request is refused where none is saved.
### Related Articles
- [The Account Balance](https://dev.wisecp.com/en/the-account-balance)
- [Affiliate Partners](https://dev.wisecp.com/en/affiliate-partners)
# API / Client API / Domains
## The Domains You Own
https://dev.wisecp.com/en/the-domains-you-own
The five endpoints that read, set, renew and extend a domain you own.
### Overview
A domain is a service too, and it carries **endpoints of its own**: the service endpoints answer not found for it. These five read a domain you own, set it, renew it and open its add-ons.
The address takes either **the domain name itself** or the service number, and both open the same record.
The capability list in the detail says which jobs can be done. It differs from provider to provider, so the interface should be built **from that list**.
### Reference
#### Listing the Domains
get/api/v1/client/domains
`Domains/GetDomains` the key's owner
Returns the account's domains.
Query 5
pageintWhich page.
limitintRows per page. 100 at the most.
statusstringThe state filter. It takes badge groups.
tldstringThe domains on this extension alone.
searchstringSearches the domain name.
Response fields data[] — 11 + meta — 4
idintThe domain's service id.
namestringThe full domain name.
tldstringThe extension. The dots stay in a multi-part one.
statusstringThe raw service state.
auto_renewboolAutomatic renewal for this domain.
lockedboolThe last known transfer lock value. The live one is read from the lock endpoint.
whois_privacyboolThe last known registration privacy value.
priceobjectThe price per period.
yearsintThe term in years.
registered_atstringThe day it was registered.
due_datestringThe day it expires and renews.
totalintHow many domains there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains?tld=com' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains?status=active', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const expiring = data.filter((d) => d.due_date && d.due_date < horizon);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains?status=active');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The lock and privacy values are a MIRROR: the last value saved rather than the current one.
$rows = Kernel::internal('client:Domains/GetDomains', ['owner_id' => $uid])['data'];
// for the live one: client:Domains/GetTransferLock
```
#### Reading a Domain
get/api/v1/client/domains/{domain}
`Domains/GetDomain` a capability probe
Returns a domain, what its provider can do and the renewal terms.
Response fields data — 17
idintThe domain's service id.
namestringThe full domain name.
tldstringThe extension. The dots stay in a multi-part one.
statusstringThe raw service state.
auto_renewboolAutomatic renewal for this domain.
lockedboolThe last known transfer lock value. The live one is read from the lock endpoint.
whois_privacyboolThe last known registration privacy value.
priceobjectThe price per period.
yearsintThe term in years.
registered_atstringThe day it was registered.
due_datestringThe day it expires and renews.
order_idintThe order that brought it into being.
auto_renew_lockedboolWhether account-wide automatic payment is on. The per-domain switch cannot move while it is.
billing_profile_idintThe billing profile assigned.
nameserversstring[]The name servers on record. Empty slots drop out.
capabilitiesobjectWhat the provider supports. Eleven fields: name servers, the transfer lock, the transfer code, child name servers, reading and writing records, signing, e-mail and address forwarding, registrant details and privacy.
addonsobjectWhere the domain add-ons stand. Each carries a state, whether it is free, a price and any invoice waiting.
renewalobjectThe renewal terms. It carries whether it is open, any subscription block, the registry ceiling and the priced term rows.
verificationstringWhere registrant verification stands. Uploading a document happens in the panel alone.
Errors 2
not_found404No such domain, it is not yours, or access to it is restricted.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.capabilities.dns_records) showDnsTab();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Build the interface FROM THE CAPABILITIES: not every provider does everything, and a closed surface answers 422.
$d = Kernel::internal('client:Domains/GetDomain',
['owner_id' => $uid, 'domain' => $domain])['data'];
$tabs = array_keys(array_filter($d['capabilities']));
```
#### Changing the Domain Preferences
patch/api/v1/client/domains/{domain}
`Domains/UpdateDomain` two fields
Changes automatic renewal and the billing profile.
Body 2
auto_renewboolAutomatic renewal for this domain. On a live domain alone, and with a true boolean.
billing_profile_idintThe billing profile id. Zero returns to the account default.
Response fields data — 17
dataobjectThe domain as it now stands. Same shape as the read endpoint.
Errors 7
not_found404No such domain, it is not yours, or access to it is restricted.
nothing_to_update422The body holds no field that can be updated.
auto_renew_invalid422The value is not a boolean.
not_actionable422Automatic renewal was sent while the domain is not live.
autorenew_locked422Account-wide automatic payment is on.
no_auto_pay_source422There is no source to charge.
billing_profile_rejected422A hook refused the profile assignment.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/client/domains/example.com' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"auto_renew":true}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ auto_renew: true }),
});
if (res.status === 422) explainLock(await res.json());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['auto_renew' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// With automatic renewal off a domain expires QUIETLY: setting a reminder is left to you.
Kernel::internal('client:Domains/UpdateDomain',
['owner_id' => $uid, 'domain' => $domain, 'auto_renew' => true]);
```
#### Raising a Renewal Invoice
post/api/v1/client/domains/{domain}/renew
`Domains/RenewDomain` it raises an invoice
Raises a renewal invoice for the number of years asked.
Body 1
yearsintreqThe term in years. It has to be one of the priced term rows in the detail.
Response fields data — 8
invoice_idintThe invoice id.
numberstringThe number shown.
statusstringThe raw invoice state.
statestringThe state shown.
totalobjectThe total with tax.
created_atstringThe day it was raised.
paid_atstringThe day it was paid.
due_datestringThe day it falls due.
Errors 4
not_found404No such domain, it is not yours, or access to it is restricted.
not_renewable422The domain cannot be renewed, or a subscription collects it.
years_invalid422The term is none of those offered.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/renew' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"years":2}'
```
```javascript
const d = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}`, {
headers: { Authorization: `Bearer ${clientKey}` },
}).then((r) => r.json());
const terms = d.data.renewal.terms;
await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/renew`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ years: terms[0].years }),
});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/renew');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['years' => 2]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The terms offered are bounded by THE REGISTRY CEILING: a ten-year name may take no further two.
$d = Kernel::internal('client:Domains/GetDomain',
['owner_id' => $uid, 'domain' => $domain])['data'];
$years = array_column($d['renewal']['terms'], 'years');
```
#### Buying a Domain Add-on
post/api/v1/client/domains/{domain}/addons/{key}
`Domains/BuyDomainAddon` a prorated first period
Buys the name management, privacy or forwarding add-on.
Body —
——No body is needed. The domain and the add-on key come from the path, and the term is fixed at one year aligned to the domain; send an empty body.
Response fields data — 9
invoice_idintThe invoice to pay.
numberstringThe number shown.
statusstringThe raw invoice state.
statestringThe state shown.
totalobjectThe prorated total of the first period.
created_atstringThe day it was raised.
paid_atstring | nullThe day it was paid. It stays null until the invoice is paid.
due_datestringThe last day to pay.
addonstringThe add-on ordered.
Errors 10
not_found404The add-on key is none of the three values, or the domain was not found.
not_actionable422The domain is not live.
addon_not_supported422The provider offers no such surface.
addon_not_offered422The operator does not sell this add-on on this extension.
addon_free422The add-on is free on this extension. There is nothing to buy.
addon_active422The add-on is already live.
addon_pending422An unpaid add-on invoice is already open.
addon_rejected422A site policy vetoed the purchase. The message carries the reason.
addon_term_invalid422No term is left to prorate, or the amount falls to zero.
addon_failed500The invoice or the record could not be made.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/addons/whois-privacy' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/addons/${key}`, {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
goPay(data.invoice_id);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/addons/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// An add-on does not open until THE INVOICE IS PAID: the purchase call raises the document alone.
$inv = Kernel::internal('client:Domains/BuyDomainAddon',
['owner_id' => $uid, 'domain' => $domain, 'key' => 'whois-privacy'])['data'];
Kernel::internal('client:Invoices/PayInvoice',
['owner_id' => $uid, 'id' => $inv['invoice_id'], 'payment' => ['method' => 'balance']]);
```
### Pitfalls
> **The capabilities follow the provider**
>
> The capability list in the detail carries **eleven fields** and no provider offers them all. Calling a closed surface comes back with a plain error. Draw the tabs and the buttons from that list, since a fixed interface breaks when the provider changes.
> **The lock and privacy values are a mirror**
>
> The transfer lock and privacy values in the listing and the detail are **the last ones saved** rather than the provider's current state. Read the real value live from the lock endpoint. On a domain where the mirror was never written the safe assumption is locked.
> **An add-on does not open until the invoice is paid**
>
> Buying an add-on **raises an invoice** and nothing more; the surface stays closed until it is paid. A second purchase is refused while one waits, and the answer says which invoice blocks it. The first period is prorated to the time left.
> **The renewal terms are bounded by the registry ceiling**
>
> The renewal rows in the detail show the terms the operator prices **and** that fit under the registry's total ceiling. A domain expiring far out can leave one year in the list, or none. Pick the term from the list rather than guessing.
> **With automatic renewal off the reminder is yours**
>
> A domain with automatic renewal off expires **quietly** on its due date and enters the recovery window. The API gives no separate warning. Read the expiry from the listing and set a reminder of your own.
### Related Articles
- [Name Servers and Records](https://dev.wisecp.com/en/name-servers-and-records)
- [Domain Contacts and Privacy](https://dev.wisecp.com/en/domain-contacts-and-privacy)
- [Taking a Domain](https://dev.wisecp.com/en/taking-a-domain)
## Taking a Domain
https://dev.wisecp.com/en/taking-a-domain
The nine endpoints that register, transfer and control the movement of a domain.
### Overview
A domain is taken in one of two ways: **registering** a new one or **moving** one from another provider. These nine endpoints cover both roads and the transfer controls around them.
Two questions come before an order: what the extension costs and for which terms it sells, and whether the name is free right now. The answer to the second is a **snapshot**.
The transfer controls work both ways. Handing a domain to someone else means opening the lock and asking for the code; bringing one here means having it opened at the other end and writing the code down here.
### Reference
#### Reading the Extension Prices
get/api/v1/client/domains/tlds
`Domains/GetTlds` the wallet currency
Returns the extensions on sale with their terms and prices.
Query 1
tldstringOne extension. It narrows the list and adds the price table per term.
Response fields data[] — 7
tldstringThe extension.
min_yearsintThe shortest term.
max_yearsintThe longest term.
registerobjectThe one-year registration price. The price before a discount comes too where a promotion runs.
transferobjectThe one-year transfer price. It comes empty where the extension has no transfer price.
renewalobjectThe one-year renewal price.
register_yearsobjectThe registration price per term. It comes only when one extension is asked for, and a term with no entry is not sold.
Errors 3
not_found404The extension asked for is not sold.
domains_not_offered422The operator does not sell domains.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/tlds?tld=com' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/tlds?tld=com', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const years = Object.keys(data[0].register_years ?? {});
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/tlds?tld=com');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The price per term comes ONLY when one extension is asked for: the general listing holds no such table.
$one = Kernel::internal('client:Domains/GetTlds', ['owner_id' => $uid, 'tld' => 'com'])['data'][0];
$priced = array_keys($one['register_years'] ?? []);
```
#### Asking Whether a Name Is Free
post/api/v1/client/domains/check
`Domains/CheckDomain` it asks the registrar
Asks live whether a domain can be taken.
Body 1
domainstringreqThe full domain to ask about.
Response fields data — 5
domainstringThe name as it was read.
statusstringThe outcome: free, taken or unknown.
premiumboolWhether the registry prices this name apart.
premium_priceobjectThe customer price of a specially priced name. It comes with the margin applied and in the wallet currency.
registerobjectThe extension's one-year price. It comes on a free name without a special price alone.
Errors 6
domains_not_offered422The operator does not sell domains.
domain_required422No domain was sent.
domain_invalid422It is not a valid domain name.
tld_not_offered422The extension is not sold.
domain_check_throttled422The shared query pool is full. Try again shortly.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/check' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"domain":"example-shop.com"}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/check', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ domain }),
});
const { data } = await res.json();
if (data.premium) showPremiumPrice(data.premium_price);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/check');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['domain' => $name]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Do not read UNKNOWN as free: the registrar could not be reached and the order can still fail.
$r = Kernel::internal('client:Domains/CheckDomain',
['owner_id' => $uid, 'domain' => $name])['data'];
$safe = $r['status'] === 'available';
```
#### Registering a Domain
post/api/v1/client/domains/register
`Domains/RegisterDomain` the balance or a saved card
Orders a new domain and collects payment.
Body 12
termsboolreqAccepting the terms. It has to be sent true.
domainstringreqThe full domain name.
yearsintThe term in years. It has to sit inside the extension's window, and a specially priced name is registered for one year whatever is sent.
accept_premiumboolAccepting the special price. It is required on such a name.
addonsstring[]The add-ons to take with it. Name management, registration privacy and forwarding, where the extension offers them.
nameserversstring[]The name servers. Two to four, and the account defaults stand in when left out.
whois_profile_idintA saved registrant profile. It fills all four roles.
contactsobjectThe contacts per role. Each role carries either a saved profile id or an inline contact, and it overrides the profile for that role.
couponsstring[]The coupon codes.
billing_profile_idintThe billing profile id.
notesstringThe order note.
paymentobjectThe payment source. The account balance or a saved card.
Response fields 201 — data — 7
order_idintThe order id.
numberstringThe order number.
actionstringThe job done: a registration or a transfer.
domainobjectThe domain service made. It carries the service id, the name, a state and the term.
totalobjectThe order total.
paymentobjectHow the collection went. It carries the road, the state, the card charged and any reason it failed.
invoiceobjectThe order invoice summary.
Errors 10
not_found404The registrant profile, the billing profile or the card belongs to another account.
domains_not_offered422The operator does not sell domains.
terms_required422The terms were not accepted.
verification_required422The account is waiting on verification.
tld_not_offered422The extension is not sold.
years_invalid422The term sits outside the extension's window.
addon_not_offered422The add-on is not offered on this extension or the key is unknown.
nameservers_invalid422The name server count or form is invalid.
contact_field_required422A required field is missing on an inline contact. Every field but the company is required.
insufficient_balance422The wallet does not cover the total.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/register' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"terms":true,"domain":"example-shop.com","years":1,"payment":{"method":"balance"}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/register', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
terms: true,
domain,
years: 1,
whois_profile_id: profileId,
payment: { method: 'balance' },
}),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/register');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($order),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A SPECIALLY PRICED name registers for ONE YEAR whatever is sent, and it wants the acceptance flag.
$c = Kernel::internal('client:Domains/CheckDomain',
['owner_id' => $uid, 'domain' => $name])['data'];
Kernel::internal('client:Domains/RegisterDomain', ['owner_id' => $uid, 'terms' => true,
'domain' => $name, 'accept_premium' => $c['premium'],
'payment' => ['method' => 'balance']]);
```
#### Transferring a Domain
post/api/v1/client/domains/transfer
`Domains/TransferDomain` a code may be needed
Moves a domain held at another provider over here.
Body 11
termsboolreqAccepting the terms. It has to be sent true.
domainstringreqThe full domain name.
auth_codestringThe transfer code from the current provider. It is required where the extension says so and is written to the service either way.
addonsstring[]The add-ons to take with it. Name management, registration privacy and forwarding, where the extension offers them.
nameserversstring[]The name servers. Two to four, and the account defaults stand in when left out.
whois_profile_idintA saved registrant profile. It fills all four roles.
contactsobjectThe contacts per role. Each role carries either a saved profile id or an inline contact, and it overrides the profile for that role.
couponsstring[]The coupon codes.
billing_profile_idintThe billing profile id.
notesstringThe order note.
paymentobjectThe payment source. The account balance or a saved card.
Response fields 201 — data — 7
order_idintThe order id.
numberstringThe order number.
actionstringThe job done: a registration or a transfer.
domainobjectThe domain service made. It carries the service id, the name, a state and the term.
totalobjectThe order total.
paymentobjectHow the collection went. It carries the road, the state, the card charged and any reason it failed.
invoiceobjectThe order invoice summary.
Errors 8
domains_not_offered422The operator does not sell domains.
terms_required422The terms were not accepted.
transfer_not_offered422The extension carries no transfer price.
auth_code_required422The extension wants a transfer code and none was sent.
domain_not_registered422The live check found the name free. A name that is not registered cannot be transferred.
domain_transfer_locked422The live check shows a transfer lock. Open it at the current provider.
checkout_blocked422A hook refused the order.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/transfer' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"terms":true,"domain":"example.com","auth_code":"EPP-CODE","payment":{"method":"balance"}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/transfer', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ terms: true, domain, auth_code: code, payment }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/transfer');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($order),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A transfer is ALWAYS one year and does not finish at payment: follow it on the transfer status endpoint.
$o = Kernel::internal('client:Domains/TransferDomain', ['owner_id' => $uid] + $order)['data'];
$sid = $o['domain']['service_id'];
```
#### Reading the Transfer Lock
get/api/v1/client/domains/{domain}/transfer-lock
`Domains/GetTransferLock` it reads live
Reads from the provider whether the domain is closed to transfer.
Response fields data — 2
lockedboolWhether the lock is on.
liveboolWhether the value came from the provider. False means the last known record is shown.
Errors 2
not_found404No such domain, it is not yours, or access to it is restricted.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/transfer-lock' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/transfer-lock`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (! data.live) warnStaleValue();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/transfer-lock');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Where the live flag is false the value can be old: weigh the lock decision against it.
$l = Kernel::internal('client:Domains/GetTransferLock',
['owner_id' => $uid, 'domain' => $domain])['data'];
$trusted = $l['live'];
```
#### Changing the Transfer Lock
put/api/v1/client/domains/{domain}/transfer-lock
`Domains/UpdateTransferLock` it writes to the provider
Closes the domain to transfer or opens it.
Body 1
lockedboolreqThe new lock state. It has to be a true boolean, and text or a number is refused.
Response fields data — 1
lockedboolThe new state the provider confirmed.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not in a live state.
locked_invalid422The value is not a boolean.
lock_not_supported422The provider module has no lock.
lock_rejected422A hook refused the change.
lock_failed422The provider refused the change.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/example.com/transfer-lock' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"locked":false}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/transfer-lock`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ locked: false }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/transfer-lock');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['locked' => false]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// OPENING the lock leaves the domain open to being taken: close it again as soon as the move is done.
Kernel::internal('client:Domains/UpdateTransferLock',
['owner_id' => $uid, 'domain' => $domain, 'locked' => false]);
```
#### Asking for the Transfer Code
post/api/v1/client/domains/{domain}/auth-code
`Domains/SendAuthCode` no code in the answer
Sends the transfer code to the domain owner's e-mail.
Body —
——No body is needed, send an empty one. The domain comes from the path and the address is the account's registered one; there is no field to send the code somewhere else.
Response fields data — 1
sentboolWhether the send ran. The code itself never appears in the answer.
Errors 5
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not in a live state.
auth_code_not_supported422The provider module gives no code.
auth_code_rejected422A hook refused the request.
auth_code_failed422The provider could not give the code.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/auth-code' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/auth-code`, {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
if (res.ok) tellUserToCheckEmail();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/auth-code');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The code NEVER comes back in the answer: it goes to the owner's e-mail, which is a deliberate safeguard.
Kernel::internal('client:Domains/SendAuthCode', ['owner_id' => $uid, 'domain' => $domain]);
```
#### Saving an Incoming Transfer Code
put/api/v1/client/domains/{domain}/auth-code
`Domains/SaveAuthCode` the key's owner
Updates the code for a transfer under way.
Body 1
codestringreqThe new transfer code. Markup is stripped and the spaces are trimmed.
Response fields data — 1
savedboolWhether the save ran.
Errors 4
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not in a live state.
code_required422The code is empty or ends up empty once cleaned.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/example.com/auth-code' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"code":"NEW-EPP-CODE"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/auth-code`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ code }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/auth-code');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['code' => $code]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This endpoint SAVES and does not restart the transfer: a changed code still wants a fresh attempt at the provider.
Kernel::internal('client:Domains/SaveAuthCode',
['owner_id' => $uid, 'domain' => $domain, 'code' => $code]);
```
#### Asking Where a Transfer Is
get/api/v1/client/domains/{domain}/transfer-status
`Domains/GetTransferStatus` it asks live
Reads from the provider where a transfer under way stands.
Response fields data — 4
service_idintThe domain's service id.
domainstringThe domain name.
statusstringThe service's raw state.
transferobject transferWhere the transfer stands.
statestringWhether it runs or finished.
liveboolWhether the provider answered live.
messagestringThe provider's note on progress. It carries the error where the live read failed.
expires_atstringThe expiry date reported once it finishes.
last_checkedstringWhen it was last asked. This call moves the value.
Errors 3
not_found404No such domain, it is not yours, or access to it is restricted.
not_a_transfer422The domain was not taken through a transfer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/transfer-status' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/transfer-status`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
showProgress(data.transfer.state, data.transfer.message);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/transfer-status');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Every call goes LIVE to the provider: do not poll it often in a watcher, hourly is plenty.
$t = Kernel::internal('client:Domains/GetTransferStatus',
['owner_id' => $uid, 'domain' => $domain])['data'];
$done = $t['transfer']['state'] === 'completed';
```
### Pitfalls
> **An unknown answer does not mean free**
>
> The availability check gives three answers and **unknown** is one of them: the registrar could not be reached. Treating it as free and ordering leads to a failure at registration. Trust a plain free answer alone.
> **A specially priced name registers for one year**
>
> On a name the registry prices apart the term field is **ignored** and the registration runs one year. Such a name also wants the flag accepting the special price, and the order is refused without it. Read the price from the availability answer.
> **Opening the lock leaves the domain exposed**
>
> The transfer lock stops your domain being moved without permission. Opening it **takes that protection away** for as long as it stays open. Close it again as soon as the move is done, since nobody does it for you.
> **The transfer code never comes back in the answer**
>
> The endpoint asking for a code says **sent** and nothing more; the code goes to the domain owner's e-mail. That is a deliberate safeguard: a stolen API key cannot move a domain in one call. Do not try to show the code in an interface.
> **The lock value is not always live**
>
> The lock read carries a **live flag**. Where the provider offers no reader or the read fails, the last known value comes back and it may not match reality. Check that flag in any flow that decides on the lock.
> **A transfer does not end at payment**
>
> Paying for a transfer order is where the work **begins**: the domain waits on approval at the other end and that can take days. The term is one year either way. Follow it on the transfer status endpoint, and ask rarely since every call reaches the provider.
### Related Articles
- [The Domains You Own](https://dev.wisecp.com/en/the-domains-you-own)
- [Domain Contacts and Privacy](https://dev.wisecp.com/en/domain-contacts-and-privacy)
- [Name Servers and Records](https://dev.wisecp.com/en/name-servers-and-records)
## Name Servers and Records
https://dev.wisecp.com/en/name-servers-and-records
The fourteen endpoints deciding where a domain points.
### Overview
Where a domain points is decided in two layers. The **name servers** say which server answers the questions, and the **records** on that server say what the answer is.
That split reaches the endpoints: changing name servers is open on every domain, while managing the records here wants the **name management add-on**.
Three more endpoints go further. Running your own name servers means defining them under the domain, and the signature records prove the answers were not changed on the way.
### Reference
#### Reading the Name Servers
get/api/v1/client/domains/{domain}/nameservers
`Domains/GetNameservers` the key's owner
Returns a domain's name servers and the account's default set.
Response fields data — 3
nameserversstring[]The domain's current set. Four entries at most, and empty slots drop out.
defaultstring[]The account's default set.
is_customboolWhether the set differs from the default. The comparison ignores case.
Errors 2
not_found404No such domain, it is not yours, or access to it is restricted.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/nameservers' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/nameservers`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.is_custom) showResetToDefault(data.default);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/nameservers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This endpoint wants NO ADD-ON: changing name servers is open on every domain, unlike the records.
$n = Kernel::internal('client:Domains/GetNameservers',
['owner_id' => $uid, 'domain' => $domain])['data'];
$set = $n['nameservers'];
```
#### Changing the Name Servers
put/api/v1/client/domains/{domain}/nameservers
`Domains/UpdateNameservers` it moves the site
Changes a domain's name servers at the provider.
Body 1
nameserversstring[]reqThe new set. Two to four valid host names, and empty entries drop before the count.
Response fields data — 1
nameserversstring[]The set the provider accepted. It comes back in lower case.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not live.
nameservers_invalid422Fewer than two or more than four entries, or one is not a valid host name.
nameservers_not_supported422The provider module cannot write them.
nameservers_rejected422A hook refused the change.
nameservers_failed422The provider refused the change.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/example.com/nameservers' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"nameservers":["ns1.example.net","ns2.example.net"]}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/nameservers`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ nameservers: list }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/nameservers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['nameservers' => $list]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Changing the name servers MOVES THE SITE: the records on the old ones stop counting.
// Confirm the records are ready on the new servers first.
Kernel::internal('client:Domains/UpdateNameservers',
['owner_id' => $uid, 'domain' => $domain, 'nameservers' => $list]);
```
#### Reading the Default Name Servers
get/api/v1/client/domains/default-nameservers
`Domains/GetDefaultNameservers` account-wide
Returns the default set the account applies to new domains.
Response fields data — 1
nameserversstring[]The default set saved. An empty list comes where none was saved.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/default-nameservers' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/default-nameservers', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (! data.nameservers.length) promptToSetDefaults();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/default-nameservers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The default set applies to NEW registrations and never reaches back to the domains you hold.
$d = Kernel::internal('client:Domains/GetDefaultNameservers', ['owner_id' => $uid])['data'];
```
#### Saving the Default Name Servers
put/api/v1/client/domains/default-nameservers
`Domains/UpdateDefaultNameservers` account-wide
Saves the default set for new domains.
Body 1
nameserversstring[]reqThe default set. Two to four valid host names, trimmed and lowered to lower case.
Response fields data — 1
nameserversstring[]The set saved.
Errors 2
nameservers_invalid422The entry count or form is invalid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/default-nameservers' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"nameservers":["ns1.example.net","ns2.example.net"]}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/default-nameservers', {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ nameservers: list }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/default-nameservers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['nameservers' => $list]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This setting touches NO domain: it is the starting value for the registrations that follow.
Kernel::internal('client:Domains/UpdateDefaultNameservers',
['owner_id' => $uid, 'nameservers' => $list]);
```
#### Listing Your Own Name Servers
get/api/v1/client/domains/{domain}/child-nameservers
`Domains/GetChildNameservers` it reads from the provider
Returns the name servers defined under the domain.
Response fields data[] — 2
nsstringThe server's full name. It usually sits under the domain itself.
ipstringThe address on record. It comes empty where the provider reports none.
Errors 4
not_found404No such domain, it is not yours, or access to it is restricted.
child_ns_not_supported422The provider module lacks the support.
child_ns_failed500The live read failed with no record to fall back to.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/child-nameservers' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/child-nameservers`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/child-nameservers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// These records are for running YOUR OWN name servers; an ordinary domain wants none.
$g = Kernel::internal('client:Domains/GetChildNameservers',
['owner_id' => $uid, 'domain' => $domain])['data'];
```
#### Defining Your Own Name Server
post/api/v1/client/domains/{domain}/child-nameservers
`Domains/CreateChildNameserver` it writes to the registry
Defines a name server under the domain.
Body 2
hoststringreqThe server's full name. It is lowered to lower case.
ipstringreqThe server's address. Its form is checked.
Response fields data[] — 2
dataarrayThe list read afresh. Same shape as the listing endpoint.
Errors 8
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not live.
child_ns_fields422The name or the address was not sent.
child_ns_host_invalid422The name is not a valid host name.
child_ns_ip_invalid422The address is not valid.
child_ns_not_supported422The provider module lacks the support.
child_ns_rejected422A hook refused the change.
child_ns_failed422The provider refused the record.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/child-nameservers' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"host":"ns1.example.com","ip":"203.0.113.10"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/child-nameservers`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ host, ip }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/child-nameservers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(compact('host', 'ip')),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Defining one is not enough: write the name server set too to POINT the domain at it.
Kernel::internal('client:Domains/CreateChildNameserver',
['owner_id' => $uid, 'domain' => $domain, 'host' => $host, 'ip' => $ip]);
Kernel::internal('client:Domains/UpdateNameservers',
['owner_id' => $uid, 'domain' => $domain, 'nameservers' => [$host, $host2]]);
```
#### Removing Your Own Name Server
delete/api/v1/client/domains/{domain}/child-nameservers
`Domains/DeleteChildNameserver` it writes to the registry
Removes a name server defined under the domain.
Body 2
hoststringreqThe name of the server to remove.
ipstringThe address. Send it where the provider keys on the name and the address together.
Response fields data[] — 2
dataarrayThe list read afresh.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not live.
child_ns_fields422The server name was not sent.
child_ns_not_supported422The provider module lacks the support.
child_ns_rejected422A hook refused the removal.
child_ns_failed422The provider refused the removal.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/domains/example.com/child-nameservers' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"host":"ns1.example.com"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/child-nameservers`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ host }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/child-nameservers');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['host' => $host]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Removing a server that is STILL IN USE can leave other domains unreachable.
Kernel::internal('client:Domains/DeleteChildNameserver',
['owner_id' => $uid, 'domain' => $domain, 'host' => $host]);
```
#### Listing the DNS Records
get/api/v1/client/domains/{domain}/dns-records
`Domains/GetDnsRecords` an add-on is needed
Reads a domain's DNS records from the provider.
Response fields data[] — 6
identitystringThe record id on the provider's side. Some providers know a record by its type, name and value, and it comes empty there.
typestringThe record type.
namestringThe label the record answers for.
valuestringWhat the record holds.
ttlintThe lifetime in seconds. It comes zero where the provider reports none.
prioritystringThe priority on mail and service records. It comes empty on other types.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The name management add-on was not bought. An unpaid invoice or an extension that does not offer it fall at the same gate.
addon_pending422The add-on invoice is unpaid. Its id comes in the answer's detail.
dns_not_supported422The provider module cannot read records.
dns_rejected422A hook refused the read.
dns_failed500The provider read failed.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/dns-records' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/dns-records`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
if (res.status === 422) return offerAddon(await res.json());
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/dns-records');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The record id can come EMPTY: that provider knows a record by its type, name and value.
$rows = Kernel::internal('client:Domains/GetDnsRecords',
['owner_id' => $uid, 'domain' => $domain])['data'];
$keyed = (bool) ($rows[0]['identity'] ?? '');
```
#### Adding a DNS Record
post/api/v1/client/domains/{domain}/dns-records
`Domains/CreateDnsRecord` an add-on is needed
Adds a new DNS record to the domain.
Body 5
typestringreqThe record type.
namestringreqThe label it answers for. The form accepted follows the provider.
valuestringreqWhat the record holds.
ttlintThe lifetime. The provider's default stands in when left out.
priorityintThe priority. It is ignored outside mail and service records.
Response fields data[] — 6
dataarrayThe list read afresh after the add. Same shape as the listing endpoint.
Errors 7
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The name management add-on was not bought. An unpaid invoice or an extension that does not offer it fall at the same gate.
not_actionable422The domain is not live.
dns_fields422The type, the name or the value is missing.
dns_not_supported422The provider module cannot add records.
dns_rejected422A hook refused the add.
dns_failed422The provider refused the record.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/dns-records' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"type":"A","name":"www","value":"203.0.113.10","ttl":3600}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/dns-records`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ type: 'A', name: 'www', value: ip }),
});
const { data } = await res.json();
renderRecords(data);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/dns-records');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($record),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The answer returns THE FRESH LIST: refresh the screen from it rather than reading again.
$rows = Kernel::internal('client:Domains/CreateDnsRecord',
['owner_id' => $uid, 'domain' => $domain] + $record)['data'];
```
#### Editing a DNS Record
put/api/v1/client/domains/{domain}/dns-records
`Domains/UpdateDnsRecord` it keys on the id
Changes a DNS record that exists.
Body 6
identitystringThe record id from the listing. Always send it where the listing gave one.
typestringreqThe record type.
namestringreqThe record label.
valuestringreqThe new content.
ttlintThe lifetime.
priorityintThe priority.
Response fields data[] — 6
dataarrayThe list read afresh after the edit.
Errors 7
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The name management add-on was not bought. An unpaid invoice or an extension that does not offer it fall at the same gate.
not_actionable422The domain is not live.
dns_fields422The type, the name or the value is missing.
dns_edit_not_supported422The provider module cannot edit. Remove and add again on such a provider.
dns_rejected422A hook refused the edit.
dns_failed422The provider refused the change.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/example.com/dns-records' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"identity":"42","type":"A","name":"www","value":"203.0.113.20"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/dns-records`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ identity: rec.identity, ...next }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/dns-records');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($record),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Editing is ABSENT on some providers: remove and add again where the capability list closes it.
$d = Kernel::internal('client:Domains/GetDomain',
['owner_id' => $uid, 'domain' => $domain])['data'];
if (! $d['capabilities']['dns_edit']) { /* delete + create */ }
```
#### Removing a DNS Record
delete/api/v1/client/domains/{domain}/dns-records
`Domains/DeleteDnsRecord` the match narrows
Removes a DNS record.
Body 4
typestringreqThe type of the record to remove.
namestringThe record label. It narrows the match.
valuestringThe record content. It narrows the match.
identitystringThe record id from the listing. It is the surest selector.
Response fields data[] — 6
dataarrayThe list read afresh after the removal.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The name management add-on was not bought. An unpaid invoice or an extension that does not offer it fall at the same gate.
not_actionable422The domain is not live.
dns_fields422The record type was not sent.
dns_rejected422A hook refused the removal.
dns_failed422The provider refused the removal.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/domains/example.com/dns-records' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"identity":"42","type":"A","name":"www"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/dns-records`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ identity: rec.identity, type: rec.type, name: rec.name }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/dns-records');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($selector),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Sending the TYPE ALONE can remove MORE THAN ONE record of it: add the id, or the name and value.
Kernel::internal('client:Domains/DeleteDnsRecord', ['owner_id' => $uid, 'domain' => $domain,
'identity' => $rec['identity'], 'type' => $rec['type'],
'name' => $rec['name'], 'value' => $rec['value']]);
```
#### Listing the Signature Records
get/api/v1/client/domains/{domain}/dnssec
`Domains/GetDnssecRecords` it reads from the provider
Returns a domain's signature verification records.
Response fields data[] — 5
identitystringThe row id on the provider's side.
digeststringThe signature digest.
key_tagintThe tag of the key the digest points at.
digest_typeintThe digest algorithm number. The set allowed comes from the provider module.
algorithmintThe key algorithm number.
Errors 4
not_found404No such domain, it is not yours, or access to it is restricted.
dnssec_not_supported422The provider module lacks signature support.
dnssec_failed500The provider read failed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/dnssec' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/dnssec`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const signed = data.length > 0;
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/dnssec');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// These want NO ADD-ON and do want provider support; confirm it from the capability list.
$ds = Kernel::internal('client:Domains/GetDnssecRecords',
['owner_id' => $uid, 'domain' => $domain])['data'];
```
#### Adding a Signature Record
post/api/v1/client/domains/{domain}/dnssec
`Domains/CreateDnssecRecord` the algorithm is checked
Adds a signature verification record to the domain.
Body 4
key_tagintreqThe key tag.
algorithmintreqThe key algorithm number. It has to sit in the set the module reports.
digest_typeintreqThe digest algorithm number. It has to sit in the set the module reports.
digeststringreqThe signature digest.
Response fields data[] — 5
dataarrayThe set read afresh.
Errors 8
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not live.
dnssec_fields422One of the required fields is missing.
dnssec_not_supported422The provider module cannot add.
dnssec_digest_type_invalid422The digest algorithm is outside the set allowed. The numbers allowed come in the answer's detail.
dnssec_algorithm_invalid422The key algorithm is outside the set allowed.
dnssec_rejected422A hook refused the add.
dnssec_failed422The provider refused the record.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/dnssec' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"key_tag":12345,"algorithm":13,"digest_type":2,"digest":"A1B2C3"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/dnssec`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(ds),
});
if (res.status === 422) showAllowed(await res.json());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/dnssec');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($ds),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The set of algorithms allowed follows THE PROVIDER: read the refusal and show the allowed list.
try { Kernel::internal('client:Domains/CreateDnssecRecord',
['owner_id' => $uid, 'domain' => $domain] + $ds); }
catch (\Throwable $e) { $allowed = $e->details['allowed'] ?? []; }
```
#### Removing a Signature Record
delete/api/v1/client/domains/{domain}/dnssec
`Domains/DeleteDnssecRecord` it can break the site
Removes a signature verification record.
Body 5
digeststringreqThe digest of the record to remove.
key_tagintreqThe record's key tag.
digest_typeintIt narrows the match.
algorithmintIt narrows the match.
identitystringThe row id from the listing. It is the surest selector.
Response fields data[] — 5
dataarrayThe set read afresh after the removal.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not live.
dnssec_fields422The digest or the key tag is missing.
dnssec_not_supported422The provider module cannot remove.
dnssec_rejected422A hook refused the removal.
dnssec_failed422The provider refused the removal.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/domains/example.com/dnssec' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"key_tag":12345,"digest":"A1B2C3"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/dnssec`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ key_tag: ds.key_tag, digest: ds.digest }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/dnssec');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($selector),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Unsign the zone BEFORE removing the last record: the wrong order leaves the domain unresolvable.
$ds = Kernel::internal('client:Domains/GetDnssecRecords',
['owner_id' => $uid, 'domain' => $domain])['data'];
$isLast = count($ds) === 1;
```
### Pitfalls
> **Records want the add-on and name servers do not**
>
> The DNS record endpoints sit behind the **name management add-on**. Unbought, or with its invoice unpaid, they all refuse. The answer says which case it is. The name server endpoints pass no such gate and work on every domain.
> **Changing name servers leaves the records behind**
>
> Changing the name server set sends the domain's questions to **a different server**. The records you entered here stay on the old one and nobody asks them any more. Do not change the set before confirming the records are ready on the new servers.
> **The record id does not come from every provider**
>
> Some providers key a record by an id and others know it by its type, name and value. In the second case the id comes **empty**. Always send the id on an edit or a removal where one exists. Give the full triple where none does, or the wrong record can be picked.
> **Sending the type alone can remove several**
>
> Only the record type is required on a removal, while the name and the value **narrow the match**. Sending the type alone can take several records of that type at once. Add the name and the value even where you hold no id.
> **Removing a signature in the wrong order breaks the domain**
>
> While signature verification is on, the record at the registry and the signature in the zone **have to agree**. Removing the last record while the zone is still signed, or unsigning the zone while the record stands, leaves the domain unresolvable. Unsign the zone first and remove the record after.
> **Your own name server wants two steps**
>
> Defining a name server under the domain only **brings it into being**. The domain uses it once you write the name server set as well. Skipping that second step leaves the definition at the registry with nothing changed.
### Related Articles
- [The Domains You Own](https://dev.wisecp.com/en/the-domains-you-own)
- [Setting Up Forwarding](https://dev.wisecp.com/en/setting-up-forwarding)
- [Domain Contacts and Privacy](https://dev.wisecp.com/en/domain-contacts-and-privacy)
## Domain Contacts and Privacy
https://dev.wisecp.com/en/domain-contacts-and-privacy
The nine endpoints governing who a domain is registered to and who sees it.
### Overview
Every domain carries contact details in **four roles**: the registrant, the administrative, the technical and the billing one. They sit at the registry and on most extensions a public lookup shows them.
**Contact profiles** are kept at the account level to save writing the same details onto every domain. A profile applies to all four roles at once, and the default one is used by itself on new registrations.
The privacy setting stops those details showing in a public lookup. It is free on some extensions and wants an **add-on** on others.
### Reference
#### Reading the Domain Contacts
get/api/v1/client/domains/{domain}/whois
`Domains/GetWhoisContacts` it reads from the provider
Returns the contact details in a domain's four roles.
Response fields data — 4
registrantobject registrantThe registrant. This is the domain's legal holder.
first_namestringThe first name.
last_namestringThe last name.
namestringThe full name shown. It is built from the two where none is stored.
companystringThe organisation.
emailstringThe e-mail.
phonestringThe phone.
addressstringThe address.
citystringThe city.
statestringThe state.
zipstringThe postcode.
countrystringThe country code.
administrativeobjectThe administrative contact. It carries the same fields.
technicalobjectThe technical contact.
billingobjectThe billing contact.
Errors 4
not_found404No such domain, it is not yours, or access to it is restricted.
whois_not_supported422The provider module could not be set up.
whois_rejected422A hook refused the read.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/whois' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/whois`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
renderContact(data.registrant);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/whois');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// All four roles ALWAYS come back; where the provider keeps one contact, all four carry it.
$w = Kernel::internal('client:Domains/GetWhoisContacts',
['owner_id' => $uid, 'domain' => $domain])['data'];
$same = $w['registrant']['email'] === $w['technical']['email'];
```
#### Writing the Domain Contacts
put/api/v1/client/domains/{domain}/whois
`Domains/UpdateWhoisContacts` it writes to the registry
Writes one contact into a chosen role or into all four.
Body 2
rolestringWhich roles to write into. All four are written when it is left out.
contactobjectreq contactThe contact to write.
first_namestringreqThe person's first name.
last_namestringreqThe person's last name.
companystringThe organisation. It is the one optional field.
emailstringreqA valid e-mail.
phonestringreqThe phone.
addressstringreqThe address line.
citystringreqThe city.
statestringThe state or province. Required on a domain contact and not on a saved profile.
zipstringreqThe postcode.
countrystringreqThe country code. It is raised to upper case.
Response fields data — 4
dataobjectThe four roles as they now stand. Same shape as the read endpoint.
Errors 9
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not live.
role_invalid422The role is none of the five values.
contact_name_required422The first or last name is empty.
contact_email_invalid422The e-mail is empty or invalid.
contact_field_required422Another required field is empty. Which one comes in the answer's detail, in the provider's own key form.
whois_not_supported422The provider module cannot write contacts.
whois_rejected422A hook refused the change.
whois_failed422The provider refused the change.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/example.com/whois' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"role":"technical","contact":{"first_name":"Jane","last_name":"Cooper","email":"jane@example.com","phone":"+15551112233","address":"Sample St 42","city":"Austin","state":"TX","zip":"73301","country":"US"}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/whois`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ role: 'technical', contact }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/whois');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['role' => 'technical', 'contact' => $contact]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Changing THE REGISTRANT counts as a change of holder on some extensions and locks the domain.
// Name the role plainly to change one; the default writes into ALL FOUR.
Kernel::internal('client:Domains/UpdateWhoisContacts', ['owner_id' => $uid, 'domain' => $domain,
'role' => 'technical', 'contact' => $contact]);
```
#### Applying a Saved Profile
post/api/v1/client/domains/{domain}/whois/apply
`Domains/ApplyWhoisProfile` it fills all four roles
Writes a saved contact profile into all four roles of the domain.
Body 1
profile_idintreqThe id of the profile to apply.
Response fields data — 4
dataobjectThe four roles as they now stand.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
not_found404The profile was not found or belongs to another account.
not_actionable422The domain is not live.
whois_not_supported422The provider module cannot write contacts.
whois_rejected422A hook refused the change.
whois_failed422The provider refused the change.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/whois/apply' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"profile_id":7}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/whois/apply`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ profile_id: profileId }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/whois/apply');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['profile_id' => $pid]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This writes over ALL FOUR roles: use the write endpoint with a role to change the technical one alone.
Kernel::internal('client:Domains/ApplyWhoisProfile',
['owner_id' => $uid, 'domain' => $domain, 'profile_id' => $pid]);
```
#### Changing the Registration Privacy
put/api/v1/client/domains/{domain}/whois-privacy
`Domains/UpdateWhoisPrivacy` it can be paid for
Opens or closes the hiding of contact details in a public lookup.
Body 1
enabledboolreqWhether privacy is on. It has to be a true boolean.
Response fields data — 1
whois_privacyboolThe new state the provider confirmed.
Errors 7
not_found404No such domain, it is not yours, or access to it is restricted.
not_actionable422The domain is not live.
enabled_invalid422The value is not a boolean.
privacy_not_supported422The provider module lacks privacy support.
addon_required422Privacy is paid for on this extension and the add-on was not bought.
privacy_rejected422A hook refused the change.
privacy_failed422The provider refused the change.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/example.com/whois-privacy' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/whois-privacy`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: true }),
});
if (res.status === 422) offerAddon(await res.json());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/whois-privacy');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Privacy is FREE on some extensions and an ADD-ON on others: read the refusal and offer the purchase.
$d = Kernel::internal('client:Domains/GetDomain',
['owner_id' => $uid, 'domain' => $domain])['data'];
$state = $d['addons']['whois_privacy']['state'];
```
#### Listing the Saved Profiles
get/api/v1/client/domains/whois-profiles
`Domains/GetWhoisProfiles` account-wide
Returns the account's saved contact profiles.
Response fields data[] — 4
idintThe profile id.
namestringThe profile label.
is_defaultboolWhether it is the account default. One profile at most carries it.
contactobjectThe contact saved. The same fields as a domain contact, without the built full name, and the state can be empty.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/whois-profiles' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/whois-profiles', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const fallback = data.find((p) => p.is_default);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/whois-profiles');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The default profile applies by itself on NEW registrations and never touches the domains you hold.
$rows = Kernel::internal('client:Domains/GetWhoisProfiles', ['owner_id' => $uid])['data'];
$def = array_values(array_filter($rows, fn ($p) => $p['is_default']))[0] ?? null;
```
#### Creating a Profile
post/api/v1/client/domains/whois-profiles
`Domains/CreateWhoisProfile` account-wide
Saves a contact profile you can reuse.
Body 2
namestringreqThe profile label.
contactobjectreq contactThe contact to save. The state is not required here.
first_namestringreqThe person's first name.
last_namestringreqThe person's last name.
companystringThe organisation. It is the one optional field.
emailstringreqA valid e-mail.
phonestringreqThe phone.
addressstringreqThe address line.
citystringreqThe city.
statestringThe state or province. Required on a domain contact and not on a saved profile.
zipstringreqThe postcode.
countrystringreqThe country code. It is raised to upper case.
Response fields data[] — 4
dataobject[]The profile list as it now stands. Same shape as the listing endpoint.
Errors 6
name_required422The label is empty.
contact_name_required422The first or last name is empty.
contact_email_invalid422The e-mail is empty or invalid.
contact_field_required422Another required field is empty. The state is not required here.
profile_rejected422A hook refused the save.
profile_failed500The profile record could not be made.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/whois-profiles' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Company","contact":{"first_name":"Jane","last_name":"Cooper","email":"jane@example.com","phone":"+15551112233","address":"Sample St 42","city":"Austin","zip":"73301","country":"US"}}'
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/domains/whois-profiles', {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name, contact }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/whois-profiles');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(compact('name', 'contact')),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The STATE is not required on a profile and CAN BE on a domain; filling it in is the safe road.
Kernel::internal('client:Domains/CreateWhoisProfile',
['owner_id' => $uid, 'name' => $name, 'contact' => $contact]);
```
#### Updating a Profile
put/api/v1/client/domains/whois-profiles/{pid}
`Domains/UpdateWhoisProfile` the whole contact
Rewrites a saved profile.
Body 2
namestringreqThe new label.
contactobjectreq contactThe whole contact. The saved one is replaced entirely.
first_namestringreqThe person's first name.
last_namestringreqThe person's last name.
companystringThe organisation. It is the one optional field.
emailstringreqA valid e-mail.
phonestringreqThe phone.
addressstringreqThe address line.
citystringreqThe city.
statestringThe state or province. Required on a domain contact and not on a saved profile.
zipstringreqThe postcode.
countrystringreqThe country code. It is raised to upper case.
Response fields data[] — 4
dataobject[]The profile list as it now stands. Same shape as the listing endpoint.
Errors 6
not_found404No such profile, or it belongs to another account.
name_required422The label is empty.
contact_name_required422The first or last name is empty.
contact_email_invalid422The e-mail is empty or invalid.
contact_field_required422Another required field is empty.
profile_rejected422A hook refused the save.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/whois-profiles/7' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"Company","contact":{"first_name":"Jane","last_name":"Cooper","email":"new@example.com","phone":"+15551112233","address":"New St 7","city":"Austin","zip":"73301","country":"US"}}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/whois-profiles/${pid}`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name, contact }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/whois-profiles/' . $pid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(compact('name', 'contact')),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Updating a profile DOES NOT reach the domains USING it: apply it again to each of them.
Kernel::internal('client:Domains/UpdateWhoisProfile',
['owner_id' => $uid, 'pid' => $pid, 'name' => $name, 'contact' => $contact]);
foreach ($domains as $d)
Kernel::internal('client:Domains/ApplyWhoisProfile',
['owner_id' => $uid, 'domain' => $d, 'profile_id' => $pid]);
```
#### Removing a Profile
delete/api/v1/client/domains/whois-profiles/{pid}
`Domains/DeleteWhoisProfile` account-wide
Removes a saved contact profile.
Response fields data[] — 4
dataobject[]The profile list as it now stands. Deleting the default promotes the one left at the top.
Errors 2
not_found404No such profile, or it belongs to another account.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/domains/whois-profiles/7' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/whois-profiles/${pid}`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${clientKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/whois-profiles/' . $pid);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Removing a profile DOES NOT change the contacts on the domains using it: the registry keeps them.
Kernel::internal('client:Domains/DeleteWhoisProfile', ['owner_id' => $uid, 'pid' => $pid]);
```
#### Making a Profile the Default
post/api/v1/client/domains/whois-profiles/{pid}/default
`Domains/SetDefaultWhoisProfile` account-wide
Sets the profile applied by itself on new registrations.
Body —
——No body is needed; send an empty one. The profile comes from the path, and there are no query parameters either.
Response fields data[] — 4
dataobject[]The profile list as it now stands, the default first. Same shape as the listing endpoint.
Errors 2
not_found404No such profile, or it belongs to another account.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/whois-profiles/7/default' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/whois-profiles/${pid}/default`, {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/whois-profiles/' . $pid . '/default');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The default is used on new registrations and transfers ALONE; it never reaches the domains you hold.
Kernel::internal('client:Domains/SetDefaultWhoisProfile', ['owner_id' => $uid, 'pid' => $pid]);
```
### Pitfalls
> **With no role named all four are written**
>
> The role field on the contact write is optional, and leaving it out writes the contact into **all four roles**. Forgetting it while meaning to change the technical contact changes the registrant as well. The profile apply endpoint always writes all four.
> **Changing the registrant can count as a transfer of holder**
>
> The registrant is the domain's **legal holder**. On some extensions changing those details counts as a transfer of holder: the registry sends a confirmation e-mail and closes the domain to transfer for a while. That can follow even when you are only fixing a typo.
> **Updating a profile does not update the domains**
>
> A saved profile is a **template**: applying it copies the details onto the domain there and then. Editing it later does not reach those domains, and removing it takes nothing off the registry. Apply it again to each domain to spread a change.
> **The state field behaves differently in two places**
>
> The state field is **not required** on a saved profile and is on a domain contact. Applying a profile saved without it can fail where the provider wants it. Save your profiles with the state filled in.
> **Privacy is not free on every extension**
>
> Privacy is free on some extensions and opens straight away, while others want an **add-on** bought first and refuse the call without it. Read which case you are in from the add-on block in the domain detail.
> **The default profile works on new registrations alone**
>
> Making a profile the default applies it by itself on the registrations and transfers **that follow**. It touches none of the domains you hold. Apply it to each of them separately to bring the existing ones into line.
### Related Articles
- [The Domains You Own](https://dev.wisecp.com/en/the-domains-you-own)
- [Taking a Domain](https://dev.wisecp.com/en/taking-a-domain)
- [Name Servers and Records](https://dev.wisecp.com/en/name-servers-and-records)
## Setting Up Forwarding
https://dev.wisecp.com/en/setting-up-forwarding
The six endpoints carrying what arrives at a domain somewhere else.
### Overview
Forwarding is **carrying what arrives** at a domain somewhere else. It comes in two kinds and both sit behind the same add-on: mail forwarding carries the post, and address forwarding carries the visitor.
The two differ in number: mail forwarding is **a list** with a rule per local part, while an address forward is **one** per domain.
Forwarding is not hosting. No mail is stored and no page is served; what arrives is handed on to another address and nothing more.
### Reference
#### Listing the Mail Forwards
get/api/v1/client/domains/{domain}/email-forwards
`Domains/GetEmailForwards` an add-on is needed
Returns the mail forwards defined on the domain.
Response fields data[] — 4
identitystringThe record id on the provider's side. A steady value is worked out from the source and target where the provider gives none.
prefixstringThe local part on the domain. It sits left of the sign.
sourcestringThe full source address. It is always the local part joined to the domain.
targetstringThe box the mail goes to.
Errors 5
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The forwarding add-on was not bought. An unpaid invoice and an extension that does not offer it fall at the same gate.
addon_pending422The add-on invoice is unpaid. Its id comes in the answer's detail.
email_forwarding_not_supported422The provider module lacks mail forwarding.
email_forwarding_failed500The live read failed.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/email-forwards' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/email-forwards`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
if (res.status === 422) return offerAddon(await res.json());
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/email-forwards');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A forward is NOT A MAILBOX: the mail arriving passes to another address and is kept nowhere here.
$rows = Kernel::internal('client:Domains/GetEmailForwards',
['owner_id' => $uid, 'domain' => $domain])['data'];
```
#### Adding a Mail Forward
post/api/v1/client/domains/{domain}/email-forwards
`Domains/CreateEmailForward` an add-on is needed
Adds a rule carrying mail for the domain to another box.
Body 2
prefixstringreqThe local part on the domain. The forward answers for that part joined to the domain.
targetstringreqThe target box. It has to be a valid e-mail address.
Response fields data[] — 4
dataarrayThe list read afresh after the add. Same shape as the listing endpoint.
Errors 8
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The forwarding add-on was not bought. An unpaid invoice and an extension that does not offer it fall at the same gate.
not_actionable422The domain is not live.
email_forward_fields422The local part or the target is missing.
email_forward_target_invalid422The target is not a valid e-mail address.
email_forwarding_not_supported422The provider module lacks the support.
email_forward_rejected422A hook refused the change.
email_forwarding_failed422The provider refused the rule.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/domains/example.com/email-forwards' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"prefix":"sales","target":"team@example.net"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/email-forwards`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ prefix, target }),
});
const { data } = await res.json();
renderForwards(data);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/email-forwards');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(compact('prefix', 'target')),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Send THE LOCAL PART alone: writing a full address adds the domain twice and breaks the rule.
Kernel::internal('client:Domains/CreateEmailForward',
['owner_id' => $uid, 'domain' => $domain, 'prefix' => 'sales', 'target' => $box]);
```
#### Removing a Mail Forward
delete/api/v1/client/domains/{domain}/email-forwards
`Domains/DeleteEmailForward` the match narrows
Removes a mail forwarding rule.
Body 3
prefixstringreqThe local part of the rule to remove.
targetstringThe target. Send it where the provider keys on the source and the target together.
identitystringThe record id from the listing. Send it where you hold one.
Response fields data[] — 4
dataarrayThe list read afresh after the removal.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The forwarding add-on was not bought. An unpaid invoice and an extension that does not offer it fall at the same gate.
not_actionable422The domain is not live.
email_forward_fields422The local part was not sent.
email_forwarding_not_supported422The provider module lacks the support.
email_forwarding_failed422The provider refused the removal.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/domains/example.com/email-forwards' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"prefix":"sales","target":"team@example.net"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/email-forwards`, {
method: 'DELETE',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ prefix: f.prefix, target: f.target, identity: f.identity }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/email-forwards');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($selector),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// One local part can reach SEVERAL targets: send the target too, or they can all go.
Kernel::internal('client:Domains/DeleteEmailForward', ['owner_id' => $uid, 'domain' => $domain,
'prefix' => $f['prefix'], 'target' => $f['target'], 'identity' => $f['identity']]);
```
#### Reading the Address Forward
get/api/v1/client/domains/{domain}/forwarding
`Domains/GetUrlForwarding` an add-on is needed
Returns whether the domain sends visitors on to another address.
Response fields data — 5
activeboolWhether a forward is set up.
protocolstringThe target's scheme.
methodintThe kind of forward. Permanent or temporary.
domainstringThe target without its scheme. It comes empty where none is set up.
urlstringThe full target address.
Errors 5
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The forwarding add-on was not bought. An unpaid invoice and an extension that does not offer it fall at the same gate.
addon_pending422The add-on invoice is unpaid.
url_forwarding_not_supported422The provider module lacks address forwarding.
url_forwarding_failed500The live read failed.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/domains/example.com/forwarding' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/forwarding`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.active) showTarget(data.url, data.method);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/forwarding');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// There is ONE forward per domain: setting a new one writes over the old, and no list exists.
$f = Kernel::internal('client:Domains/GetUrlForwarding',
['owner_id' => $uid, 'domain' => $domain])['data'];
```
#### Setting Up an Address Forward
put/api/v1/client/domains/{domain}/forwarding
`Domains/UpdateUrlForwarding` an add-on is needed
Sends a visitor arriving at the domain on to another address.
Body 2
urlstringreqThe full target address. Its scheme becomes the forward's, and the insecure one stands in when none is written.
methodintThe kind of forward. Permanent is the default and another value falls to it.
Response fields data — 5
dataobjectThe forward as it now stands. Same shape as the read endpoint.
Errors 7
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The forwarding add-on was not bought. An unpaid invoice and an extension that does not offer it fall at the same gate.
not_actionable422The domain is not live.
url_required422The target was not sent, or nothing is left once the scheme is taken off.
url_forwarding_not_supported422The provider module lacks the support.
url_forwarding_rejected422A hook refused the change.
url_forwarding_failed422The provider refused the change.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PUT 'https://panel.example.com/api/v1/client/domains/example.com/forwarding' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"url":"https://shop.example.net/welcome","method":301}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/forwarding`, {
method: 'PUT',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ url, method: 302 }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/forwarding');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['url' => $target, 'method' => 301]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Browsers CACHE a permanent forward: pick the temporary kind while testing and move to permanent after.
Kernel::internal('client:Domains/UpdateUrlForwarding',
['owner_id' => $uid, 'domain' => $domain, 'url' => $target, 'method' => 302]);
```
#### Removing the Address Forward
delete/api/v1/client/domains/{domain}/forwarding
`Domains/DeleteUrlForwarding` an add-on is needed
Removes the domain's address forward.
Response fields data — 5
dataobjectThe state read after the removal. Same shape as the read endpoint.
Errors 6
not_found404No such domain, it is not yours, or access to it is restricted.
addon_required422The forwarding add-on was not bought. An unpaid invoice and an extension that does not offer it fall at the same gate.
not_actionable422The domain is not live.
url_forwarding_not_supported422The provider module lacks the support.
url_forwarding_rejected422A hook refused the removal.
url_forwarding_failed422The provider refused the removal.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/domains/example.com/forwarding' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/domains/${domain}/forwarding`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/domains/' . $domain . '/forwarding');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Removing the forward leaves the domain pointing NOWHERE: a visitor lands on nothing.
// Think first about what takes its place; a record or a new target is wanted.
Kernel::internal('client:Domains/DeleteUrlForwarding',
['owner_id' => $uid, 'domain' => $domain]);
```
### Pitfalls
> **Both kinds rest on one add-on**
>
> All **six endpoints** of mail and address forwarding sit behind the forwarding add-on. Unbought, or with its invoice unpaid, they all refuse and the answer says which case it is. One purchase opens them both.
> **One address forward per domain**
>
> An address forward has no list: setting one **writes over** what was there. There is no adding a second target, and a second call replaces the first. Mail forwarding is a list and carries as many rules as you like.
> **The local part goes, not the full address**
>
> The source field on a mail forward takes **the local part** alone and the server adds the domain. Writing a full address adds the domain twice and the rule answers no mail. The source field in the answer shows the right joining.
> **Removing without a target can take several rules**
>
> One local part can forward to several targets. Sending it alone on a removal can take **every rule** bound to that part. Add the target, and the record id where you hold one.
> **A permanent forward is kept by the browser**
>
> Picking the permanent kind tells browsers and search engines the address **moved for good**, and they keep that for a long while. A permanent forward to a wrong target sends visitors there for a time even after the fix. Use the temporary kind while testing.
> **A forward is not a mailbox**
>
> A mail forward **passes the post to another box** and keeps no copy. Where the target box is full or refuses the mail, the message is lost with no trace here. A customer wanting a real box should take a mail service.
### Related Articles
- [Name Servers and Records](https://dev.wisecp.com/en/name-servers-and-records)
- [The Domains You Own](https://dev.wisecp.com/en/the-domains-you-own)
# API / Client API / Products
## What Is on Sale
https://dev.wisecp.com/en/what-is-on-sale
The three endpoints giving the products on sale, their categories and the order schema.
### Overview
These three endpoints show what a customer **can buy**. What the shop window holds is what appears here: a product that is closed, hidden or in a shut group never shows at all.
The prices come in the account's **wallet currency**. The figure listed can be compared with the balance straight away, and ordering brings no surprise.
The detail endpoint gives more than a catalogue record: it is the **schema** of the order body. The cycles, add-ons, questions and the domain axis are read from it.
### Reference
#### Listing the Products
get/api/v1/client/products
`Products/GetProducts` the wallet currency
Returns the products that can be ordered, in shop-window order.
Query 5
pageintWhich page.
limitintRows per page. 100 at the most.
typestringOne product type. An unknown type is refused and the valid list comes in the answer's detail.
categoryintThe category number. It matches the main category and the extra assignments alike.
searchstringSearches the product title.
Response fields data[] — 8 + meta — 5
idintThe product id.
typestringThe product type.
titlestringThe product name.
taglinestringA short line about it.
categoryobjectThe main category. It carries a number and a name, and comes empty on a product with none.
in_stockboolWhether it can be ordered. It closes only with stock tracking on and the counter at zero.
stockintThe stock left. Empty means it is not tracked.
pricingobject[]One price row per billing cycle.
totalintHow many products there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
currencystringThe currency every price is in. It is the account's wallet currency.
Errors 2
type_invalid422The product type is unknown or that group is closed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/products?type=hosting' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/products?type=hosting', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data, meta } = await res.json();
renderPrices(data, meta.currency);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/products?type=hosting');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The prices come in the WALLET currency: compare them with the balance straight and convert nothing.
$r = Kernel::internal('client:Products/GetProducts', ['owner_id' => $uid, 'type' => 'hosting']);
$cur = $r['meta']['currency'];
```
#### Listing the Categories
get/api/v1/client/products/categories
`Products/GetProductCategories` no paging
Returns the product categories on show as one flat list.
Query 1
typestringThe categories of this type alone. An unknown value gives an empty list rather than an error.
Response fields data[] — 4 + meta — 1
idintThe category number. This is what goes into the product listing's category filter.
parentintThe parent category. Empty means it sits at the top.
typestringThe category's product type.
namestringThe category name.
totalintHow many categories there are. It comes back under meta.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/products/categories' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/products/categories', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const roots = data.filter((c) => c.parent === null);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/products/categories');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The list is FLAT: build the tree from the parent field yourself, since the endpoint gives none.
$rows = Kernel::internal('client:Products/GetProductCategories', ['owner_id' => $uid])['data'];
$tree = [];
foreach ($rows as $c) $tree[$c['parent'] ?? 0][] = $c;
```
#### The Product and Its Order Schema
get/api/v1/client/products/{id}
`Products/GetProduct` the order input
Returns a product with everything needed to build an order body.
Response fields data — 14
idintThe product id.
typestringThe product type.
titlestringThe product name.
taglinestringA short line about it.
descriptionstringThe full description. It comes with the markup the shop shows.
categoryobjectThe main category.
in_stockboolWhether it can be ordered.
stockintThe stock left.
quantityobjectThe quantity rule. It carries a permission and a mode: one unit, each unit its own service, or a quantity scaling inside one service.
order_limit_per_userintHow many services one account may hold. Empty means there is no limit.
pricingobject[]One price row per billing cycle.
addonsobject[]The add-ons an order can pick. Each carries an id, a name, a description, an input type, whether it is required, its choices and its own questions.
requirementsobject[]The fields an order has to fill. Each carries an id, a name, an input type and whether it is required; a choice type adds its options and a file type adds the extensions allowed and any size limit.
metricsobject[]The meters charged by use. Each carries an id, a type, a label, a unit, a charging scheme, what is included, a ceiling and the tiered prices.
domainobjectThe domain axis. By its mode it carries a chooser list, subdomain roots or the licence fields.
Errors 2
not_found404The product is absent, closed, hidden or its group is shut. The four are deliberately not told apart.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/products/36' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/products/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const must = data.requirements.filter((r) => r.required);
const cycles = data.pricing.map((p) => p.cycle);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/products/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A NEW domain cannot be ordered here: registering and transferring happen on the Domains endpoints.
$pr = Kernel::internal('client:Products/GetProduct', ['owner_id' => $uid, 'id' => $id])['data'];
$viaDomains = ($pr['domain']['register_transfer'] ?? '') === 'via_domains_endpoints';
```
### Pitfalls
> **A new domain is not ordered from here**
>
> The domain axis in the product detail covers using a domain you **already own** or picking a free subdomain. Registering a new domain or transferring one belongs to the domain endpoints. Mixing them up sends you looking for an order field that does not exist.
> **The price listed is the promotional one**
>
> Where a cycle carries a promotion the price field holds the **promotional amount** and the promotion flag comes back true. Applying a discount on top of the listing takes it down twice. This is also what the order engine charges, so the listing and the basket never disagree.
> **A product not found can mean four things**
>
> The detail endpoint meets an unknown, closed, hidden and group-shut product with the **same answer**. That is deliberate: the answer never leaks whether the product exists. When one is missing from the listing the API will not say why, and the operator has to be asked.
> **The quantity mode means three different orders**
>
> The quantity rule sits in one of three modes: one unit per order, **a separate service** for each unit, or a quantity scaling inside one service. Ordering ten in the second mode brings ten services into being, and in the third one service at ten times the price. Read the mode before building the interface.
> **The category list is flat and not a tree**
>
> The categories come back flat and the hierarchy is built from the parent field. There is no paging either: the whole set comes every time. A chosen category goes into the product listing as a **filter** and does not take its children in by itself.
### Related Articles
- [Ordering as the Client](https://dev.wisecp.com/en/ordering-as-the-client)
- [Taking a Domain](https://dev.wisecp.com/en/taking-a-domain)
- [The Account Balance](https://dev.wisecp.com/en/the-account-balance)
## The Services You Own
https://dev.wisecp.com/en/the-services-you-own
The eleven endpoints that read, set, renew and end a service you own.
### Overview
A service is the thing a customer **owns**: a hosting package, a server, a software licence. These eleven endpoints read that record, change its settings, renew it and ask for it to end.
Renewal runs in two steps: these endpoints **raise an invoice** and payment happens on the invoice endpoints. Automatic renewal, meanwhile, is governed by two switches, one at the account level and one on the service.
Some products are charged by use as well. A meter can be switched, and an unpaid usage invoice **locks it shut**.
### Reference
#### Listing the Services
get/api/v1/client/services
`Services/GetServices` the key's owner
Returns the services the account owns.
Query 5
pageintWhich page.
limitintRows per page. 100 at the most.
statusstringThe state filter. It takes badge groups: pending covers both waiting and in process, and cancelled takes completed in too.
typestringThe product type filter.
searchstringSearches the service name and the domain tied to it.
Response fields data[] — 10 + meta — 4
idintThe service id.
typestringThe product type.
namestringThe service name. It is a copy of the product name at order time.
statusstringThe raw state.
hoststringThe domain or host name tied to it.
product_idintThe id of the product ordered.
auto_renewboolWhether automatic renewal is on for this service.
priceobjectThe amount per period.
cyclestringThe billing cycle.
created_atstringThe day it was set up.
due_datestringThe day the next payment falls.
totalintHow many services there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 1
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services?status=active' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch('https://panel.example.com/api/v1/client/services?status=active', {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const soon = data.filter((s) => s.due_date && s.due_date < horizon);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services?status=active');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The filter takes a BADGE GROUP rather than a raw state: pending covers two raw states at once.
$rows = Kernel::internal('client:Services/GetServices',
['owner_id' => $uid, 'status' => 'pending'])['data'];
```
#### Reading a Service
get/api/v1/client/services/{id}
`Services/GetService` the key's owner
Returns a service's settings, access details and where renewal stands.
Response fields data — 16
idintThe service id.
typestringThe product type.
namestringThe service name.
statusstringThe raw state.
productobjectThe product plan. It carries an id and a name.
hoststringThe domain or host name tied to it.
order_idintThe order that brought it into being.
managedboolWhether a panel module runs it. True means the tools and sign-in endpoints work.
auto_renewboolAutomatic renewal for this service.
auto_renew_lockedboolWhether account-wide automatic payment is on. The per-service switch cannot move while it is.
billing_profile_idintThe billing profile assigned. Zero means the account's default address.
priceobjectThe amount per period.
cyclestringThe billing cycle.
accessobjectThe access details as they stood at order time. Its keys follow the service type and an empty value never appears.
renewalobject renewalWhere renewal stands.
availableboolWhether a renewal invoice can be raised.
blocked_by_subscriptionboolWhether a subscription collects the renewals itself.
already_invoicedboolWhether the period is already invoiced.
open_invoice_idintThe open invoice it would attach to.
cyclesarrayThe renewal cycles that can be picked.
cancellationobjectAn open cancellation request. It carries a state, an urgency, a reason, a note and when it was asked.
has_metricsboolWhether a meter charged by use is defined.
Errors 2
not_found404No such service, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.renewal.available) showRenewButton(data.renewal.cycles);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A DOMAIN is NOT read here: domains have endpoints of their own and answer not found on this one.
$s = Kernel::internal('client:Services/GetService', ['owner_id' => $uid, 'id' => $id])['data'];
$panel = $s['managed'];
```
#### Changing the Service Preferences
patch/api/v1/client/services/{id}
`Services/UpdateService` two fields
Changes automatic renewal and the billing profile.
Body 2
auto_renewboolAutomatic renewal for this service. It cannot move while account-wide automatic payment is on.
billing_profile_idintThe billing profile id. Zero returns to the account default.
Response fields data — 16
dataobjectThe service as it now stands. Same shape as the read endpoint.
Errors 6
not_found404No such service, or it belongs to another customer.
nothing_to_update422The body holds no field that is known.
not_actionable422Automatic renewal was sent while the service is not live.
autorenew_locked422Account-wide automatic payment is on.
no_auto_pay_source422Turning it on was tried with no source to charge.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/client/services/622' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"auto_renew":true,"billing_profile_id":3}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ auto_renew: true }),
});
if (res.status === 422) explainLock(await res.json());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['auto_renew' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The per-service switch is LOCKED while account-wide automatic payment is on; look at the wallet setting first.
$s = Kernel::internal('client:Services/GetService', ['owner_id' => $uid, 'id' => $id])['data'];
if (! $s['auto_renew_locked'])
Kernel::internal('client:Services/UpdateService',
['owner_id' => $uid, 'id' => $id, 'auto_renew' => true]);
```
#### Raising a Renewal Invoice
post/api/v1/client/services/{id}/renew
`Services/RenewService` it raises an invoice
Raises a renewal invoice for the service.
Body 1
cyclestringThe renewal cycle. It is picked from the cycle list in the service detail, and the current one stands in when left out.
Response fields data — 8
invoice_idintThe renewal invoice id.
numberstringThe invoice number shown.
statusstringThe raw invoice state.
statestringThe state shown to the customer.
totalobjectThe invoice total.
created_atstringThe day it was raised.
due_datestringThe day it falls due.
existingboolWhether an invoice that was already open came back. True means no new document was raised.
Errors 7
not_found404No such service, or it belongs to another customer.
not_renewable422The service is neither live nor expired.
renew_blocked_subscription422A subscription collects the renewals itself.
cycle_invalid422The cycle is not one the product renews at.
already_invoiced422The period is invoiced and no open invoice waits.
renew_disabled422The operator closed renewal on this service.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/services/622/renew' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"cycle":"annually"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/renew`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ cycle }),
});
const { data } = await res.json();
if (data.existing) note('An invoice was already open.');
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/renew');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['cycle' => $cycle]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// It RAISES an invoice and PAYS nothing: hand the id it returns to the invoice payment endpoint.
$inv = Kernel::internal('client:Services/RenewService',
['owner_id' => $uid, 'id' => $id])['data'];
Kernel::internal('client:Invoices/PayInvoice',
['owner_id' => $uid, 'id' => $inv['invoice_id'], 'payment' => ['method' => 'balance']]);
```
#### Asking to Cancel
post/api/v1/client/services/{id}/cancellation
`Services/CreateCancellation` one request at a time
Opens a request to cancel the service.
Body 4
urgencystringreqWhen it should end: at once or at the end of the period.
reasonstringreqThe reason. One of five: no longer needed, too costly, moving away, missing features or other.
reason_detailstringA free explanation. It is required where the reason is other.
notestringA note to the operator.
Response fields data
dataobjectThe cancellation opened. Same shape as the cancellation field in the service detail.
Errors 5
not_found404No such service, or it belongs to another customer.
not_actionable422The service is not live.
cancellation_exists422A request is already open.
reason_detail_required422The explanation is empty on the other reason, or a value is invalid.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/services/622/cancellation' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"urgency":"period-ending","reason":"not-needed"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/cancellation`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ urgency: 'period-ending', reason, note }),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/cancellation');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['urgency' => 'period-ending', 'reason' => $why]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Choosing AT ONCE ends the service there and then: the period-end choice lets the time already paid run out.
Kernel::internal('client:Services/CreateCancellation',
['owner_id' => $uid, 'id' => $id, 'urgency' => 'period-ending', 'reason' => 'not-needed']);
```
#### Withdrawing a Cancellation
delete/api/v1/client/services/{id}/cancellation
`Services/RevokeCancellation` the key's owner
Withdraws an open cancellation request.
Response fields data — 2
revokedboolWhether the withdrawal ran.
service_idintThe service id.
Errors 2
not_found404No request stands open on this service.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X DELETE 'https://panel.example.com/api/v1/client/services/622/cancellation' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/cancellation`, {
method: 'DELETE',
headers: { Authorization: `Bearer ${clientKey}` },
});
const body = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/cancellation');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// Once a request is APPROVED withdrawing may not save the service; read its state from the detail.
$s = Kernel::internal('client:Services/GetService', ['owner_id' => $uid, 'id' => $id])['data'];
$pending = ($s['cancellation']['status'] ?? '') === 'pending';
```
#### Reading the Service Add-ons
get/api/v1/client/services/{id}/addons
`Services/GetServiceAddons` the key's owner
Returns the add-ons tied to the service.
Response fields data[] — 11
idintThe add-on record id.
addon_idintThe add-on definition id.
option_idintThe choice picked.
namestringThe add-on name.
optionstringThe choice name.
quantityintHow many were taken.
statusstringWhere the add-on stands.
priceobjectThe line total per period.
cyclestringThe billing cycle.
due_datestringThe day the next payment falls.
unpaid_invoice_idintThe unpaid purchase invoice. It fills while the add-on waits.
cancellation_requestedboolWhether it is set to end with the period.
Errors 2
not_found404No such service, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622/addons' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/addons`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const waiting = data.filter((a) => a.unpaid_invoice_id > 0);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/addons');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A waiting add-on stays asleep until its INVOICE is paid; take the id from here and pay it.
$rows = Kernel::internal('client:Services/GetServiceAddons',
['owner_id' => $uid, 'id' => $id])['data'];
$due = array_filter(array_column($rows, 'unpaid_invoice_id'));
```
#### Reading the Service Invoices
get/api/v1/client/services/{id}/invoices
`Services/GetServiceInvoices` the key's owner
Returns the documents that bill this service.
Query 1
limitintThe rows at most. 100 at the most.
Response fields data[] — 7
invoice_idintThe invoice id.
numberstringThe number shown.
statusstringThe raw state.
statestringThe state shown.
totalobjectThe document total.
created_atstringThe day it was raised.
due_datestringThe day it falls due.
Errors 2
not_found404No such service, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622/invoices' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/invoices`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const open = data.filter((i) => i.state !== 'paid');
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/invoices');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// There is NO PAGING here, only a ceiling: use the invoice listing for a long history.
$rows = Kernel::internal('client:Services/GetServiceInvoices',
['owner_id' => $uid, 'id' => $id, 'limit' => 100])['data'];
```
#### Reading the Meters
get/api/v1/client/services/{id}/metrics
`Services/GetServiceMetrics` charged by use
Returns the meters charged by use and what they are likely to cost.
Response fields data — 2
metricsobject[] metrics[]The meters.
keystringThe meter key. This is what the switch endpoint takes.
labelstringThe name shown.
unitstringIts unit.
enabledboolWhether it is measuring now.
includedfloatWhat is included free.
usagefloatThe use this period.
overagefloatThe billable use above what is included.
estimated_chargeobjectThe charge expected for the overage.
unit_priceobjectThe unit price of the first live tier.
lockedboolWhether an unpaid usage invoice blocks turning it on.
locked_by_invoice_idintThe invoice blocking it.
auto_disabledboolWhether it closed by itself over an unpaid invoice.
has_unpaidboolWhether any usage invoice on the service is unpaid. It is a lock across the whole service.
Errors 2
not_found404No such service, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622/metrics' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/metrics`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const bill = data.metrics.reduce((s, m) => s + (m.estimated_charge?.amount ?? 0), 0);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/metrics');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A meter switched off is still billed for what it USED UP TO THEN: closing it erases no history.
$m = Kernel::internal('client:Services/GetServiceMetrics',
['owner_id' => $uid, 'id' => $id])['data'];
$blocked = $m['has_unpaid'];
```
#### Switching a Meter
patch/api/v1/client/services/{id}/metrics/{key}
`Services/UpdateServiceMetric` an unpaid invoice locks it
Turns one meter on or off.
Body 1
enabledboolreqThe state wanted.
Response fields data
dataobjectThe meter as it now stands.
Errors 7
not_found404No such meter key or service.
enabled_invalid422The state field is missing or of the wrong kind.
not_actionable422The service is not live.
metric_not_priced422No live price tier exists.
metric_unpaid_lock422An unpaid usage invoice blocks turning it on.
metric_module_rejected422The panel module refused the change.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X PATCH 'https://panel.example.com/api/v1/client/services/622/metrics/storage' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"enabled":true}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/metrics/${key}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ enabled: true }),
});
if (res.status === 422) explainLock(await res.json());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/metrics/' . $key);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['enabled' => true]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The one way past the lock is PAYING THE INVOICE that blocks it; its id is written on the meter.
$m = Kernel::internal('client:Services/GetServiceMetrics',
['owner_id' => $uid, 'id' => $id])['data'];
$blocker = array_column($m['metrics'], 'locked_by_invoice_id', 'key')[$key] ?? 0;
```
#### The Usage Billing History
get/api/v1/client/services/{id}/metrics/billing
`Services/GetServiceMetricBilling` the key's owner
Returns the use billed period by period.
Query 3
pageintWhich page.
limitintRows per page. 100 at the most.
metricstringNarrows it to one meter.
Response fields data[] — 9 + meta — 4
metricstringThe meter key.
labelstringThe name shown.
unitstringIts unit.
period_startstringThe start of the period billed.
period_endstringThe end of it.
usagefloatThe use over the period.
overagefloatThe share billed.
amountobjectThe amount.
statestringWhere the row stands: pending, unpaid, paid or cancelled.
invoice_idintThe usage invoice. It is zero while nothing was billed.
totalintHow many rows there are. It comes back under meta.
pageintThe page you are on.
limitintThe page size.
next_pageintThe next page.
Errors 2
not_found404No such service, or it belongs to another customer.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622/metrics/billing?metric=storage' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const url = new URL(`https://panel.example.com/api/v1/client/services/${id}/metrics/billing`);
url.searchParams.set('metric', key);
const res = await fetch(url, { headers: { Authorization: `Bearer ${clientKey}` } });
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/metrics/billing');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// A PENDING row is a period not yet billed: its invoice id is zero and the amount can still move.
$rows = Kernel::internal('client:Services/GetServiceMetricBilling',
['owner_id' => $uid, 'id' => $id])['data'];
$open = array_filter($rows, fn ($r) => $r['state'] === 'pending');
```
### Pitfalls
> **Renewal raises an invoice and pays nothing**
>
> The renewal endpoint **produces an invoice** and stops there; the service runs longer only once that invoice is paid. A field in the answer says whether no new document was raised and an already open one came back. Hand the id to the invoice payment endpoint.
> **Two automatic renewal switches exist**
>
> While account-wide automatic payment is on the per-service switch is **locked** and a change is refused. The lock field in the detail says so beforehand. The way past it is the wallet setting rather than the service one.
> **Cancelling at once burns the time paid for**
>
> The urgency on a cancellation takes one of two values. **At once** ends the service there and then and the time already paid for does not come back, while **at the end of the period** lets it run out. Show the customer that difference.
> **Switching a meter off erases no past use**
>
> Switching a meter off **does not save** the use up to that moment from being billed: it still enters the document at period end. An unpaid usage invoice also locks the meter shut, and paying that invoice is the only key.
> **Domains do not belong to these endpoints**
>
> A domain record looks like a service and answers **not found** on these endpoints, because it has endpoints of its own. Code looking for a domain in a service listing comes back empty and can read that as a fault. See the domain articles instead.
> **The service invoice list is not paged**
>
> The endpoint giving a service's invoices takes a **ceiling** alone and no paging. Use the general invoice listing for a long history and search there. The add-on listing carries the same limit.
### Related Articles
- [Reaching Into a Service](https://dev.wisecp.com/en/reaching-into-a-service)
- [Paying an Invoice](https://dev.wisecp.com/en/paying-an-invoice)
- [The Domains You Own](https://dev.wisecp.com/en/the-domains-you-own)
## Reaching Into a Service
https://dev.wisecp.com/en/reaching-into-a-service
The seven endpoints reaching the panel behind a service.
### Overview
Behind a service there is usually a **panel**: a hosting control panel, a virtualisation interface or a software installation. These seven endpoints reach it.
They are all **live calls**: WISECP returns the panel's state at that moment rather than its own records. A slow panel makes a slow answer, and a panel that is down makes the endpoint fail.
What is opened to the customer is **kept narrow** next to the admin side. Creating, suspending and terminating are never reachable here.
### Reference
#### Reading the Panel Overview
get/api/v1/client/services/{id}/dashboard
`Services/GetServiceDashboard` it asks the module live
Returns the overview and the abilities of the panel behind the service.
Response fields data — 8
modulestringThe panel module name.
panel_namestringThe panel name shown.
sso_availableboolWhether single sign-on works. It closes while access is restricted.
can_change_passwordboolWhether the panel password can be changed here.
has_toolsboolWhether the module offers a tool surface.
methodsarrayThe module methods the customer may call. The method endpoint takes these alone.
quick_actionsarrayThe shortcuts on the overview. Each carries a key, a label and whether it runs an action.
overviewobject overviewThe state the panel reports.
gaugesarrayThe limited resources. Each carries what is used, the total and the unit, and a total at zero or below means no limit.
resourcesarrayThe counters and values the module reports.
accountarrayThe live panel account details. The sign-in details drop while access is restricted.
Errors 4
not_found404No such service, it is not yours, it has no module, or it is not live.
not_actionable422The service is not in a live state.
module_unavailable422The module could not be set up. The panel cannot be reached now.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622/dashboard' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/dashboard`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
if (data.sso_available) showOpenPanelButton();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/dashboard');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This call goes LIVE TO THE PANEL: a slow panel makes a slow answer, so cache it on screen.
$d = Kernel::internal('client:Services/GetServiceDashboard',
['owner_id' => $uid, 'id' => $id])['data'];
$can = $d['methods'];
```
#### Listing the Tools
get/api/v1/client/services/{id}/tools
`Services/GetServiceTools` it asks the module live
Returns the panel tools the service offers.
Response fields data[] — 4
keystringThe tool key. This is what the data and action endpoints take.
groupstringThe panel's grouping.
labelstringThe name shown.
capabilitiesarrayThe actions the tool supports. Creating, editing, removing and the like.
Errors 3
not_found404No such service, it is not yours, it has no module, or it is not live.
tools_not_supported422The module has no tool surface.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622/tools' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/tools`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
const byGroup = Object.groupBy(data, (t) => t.group);
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/tools');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The customer list is NARROWER than the admin one: the tools opened to the customer area come alone.
$tools = Kernel::internal('client:Services/GetServiceTools',
['owner_id' => $uid, 'id' => $id])['data'];
$keys = array_column($tools, 'key');
```
#### Reading a Tool's Data
get/api/v1/client/services/{id}/tools/{tool}
`Services/GetServiceToolData` it asks the module live
Pulls what a tool lists from the panel.
Query 1
actionstringThe read action. The tool's default listing stands in when left out.
Response fields data
dataobjectWhat the tool returns. Its shape follows the tool and the module, and there is no fixed contract.
Errors 5
not_found404The tool is unknown or the service was not found.
tools_not_supported422The module has no tool surface.
tool_rejected422A hook refused the call.
tool_data_failed500The call to the panel failed.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl 'https://panel.example.com/api/v1/client/services/622/tools/databases' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/tools/${tool}`, {
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/tools/' . $tool);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The shape belongs to THE MODULE and is no API contract: the fields move when the server panel does.
$rows = Kernel::internal('client:Services/GetServiceToolData',
['owner_id' => $uid, 'id' => $id, 'tool' => $tool])['data'];
```
#### Running a Tool Action
post/api/v1/client/services/{id}/tools/{tool}/{action}
`Services/RunServiceToolAction` it changes the server
Runs a create, an edit or a removal on a tool.
Body —
*objectA free body belonging to the tool. Its fields are what the module expects.
Response fields data
dataobjectWhat the module gave back.
Errors 5
not_found404No such service, it is not yours, it has no module, or it is not live.
tools_not_supported422The module has no tool surface.
tool_rejected422A hook refused the call.
tool_action_failed500The call to the panel threw an error.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/services/622/tools/databases/create' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"name":"shop"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/tools/${tool}/${action}`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
const { data } = await res.json();
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/tools/' . $tool . '/' . $action);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode($payload),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// This call makes a real change ON THE SERVER and cannot be undone: put a removal behind a confirmation.
$out = Kernel::internal('client:Services/RunServiceToolAction',
['owner_id' => $uid, 'id' => $id, 'tool' => $tool, 'action' => 'create'] + $payload);
```
#### Running a Module Method
post/api/v1/client/services/{id}/module-method
`Services/UseServiceModuleMethod` declared methods only
Runs a method the module opened to the customer.
Body 1
methodstringreqThe method to run. It comes from the method list in the panel overview.
Response fields data — 4
methodstringThe method that ran.
redirect_urlstringThe address the module produced. It fills on a download or a redirect flow.
resultobjectWhat the method returned.
outputstringThe output caught where the method printed rather than returned.
Errors 6
not_found404No such service, it is not yours, it has no module, or it is not live.
method_required422No method name was sent.
invalid_method422The method was never declared open to the customer.
module_unavailable422The module could not be set up.
tool_rejected422A hook refused the call.
module_method_failed500The module method threw an error.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/services/622/module-method' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"method":"backup_download"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/module-method`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ method }),
});
const { data } = await res.json();
if (data.redirect_url) window.location = data.redirect_url;
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/module-method');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['method' => $method]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// DECLARED methods alone can be called: creating, suspending and terminating are never reachable here.
$d = Kernel::internal('client:Services/GetServiceDashboard',
['owner_id' => $uid, 'id' => $id])['data'];
if (in_array($method, $d['methods'], true))
Kernel::internal('client:Services/UseServiceModuleMethod',
['owner_id' => $uid, 'id' => $id, 'method' => $method]);
```
#### Signing Into the Panel
post/api/v1/client/services/{id}/sso
`Services/GetServiceSso` a short-lived address
Makes a one-time address for signing into the panel without a password.
Body —
——No body is needed, so send an empty one. The panel account comes from the service record.
Response fields data — 1
urlstringThe address opening the panel. It is short-lived and not meant to be kept.
Errors 5
not_found404The service was not found, has no module, is not live, or access is restricted.
sso_not_supported422The module offers no single sign-on.
tool_rejected422A hook refused the call.
sso_failed500The module returned no address.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/services/622/sso' \
-H "Authorization: Bearer $CLIENT_KEY"
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/sso`, {
method: 'POST',
headers: { Authorization: `Bearer ${clientKey}` },
});
const { data } = await res.json();
window.open(data.url, '_blank');
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/sso');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $clientKey],
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The address is SHORT-LIVED and single use: never cache it and make a new one on each open.
$sso = Kernel::internal('client:Services/GetServiceSso',
['owner_id' => $uid, 'id' => $id])['data'];
header('Location: ' . $sso['url']);
```
#### Changing the Panel Password
post/api/v1/client/services/{id}/password
`Services/ChangeServicePassword` hosting and servers
Changes the panel password of the service.
Body 1
passwordstringreqThe new panel password. It has to meet the operator's least length.
Response fields data
dataobjectHow the change went.
Errors 5
not_found404No such service, it is not yours, it has no module, or it is not live.
password_too_short422The password is under the least length. That least value comes in the answer's detail.
password_not_supported422The service type does not suit, access is restricted, or the module lacks the ability.
password_change_failed422The panel refused the change.
insufficient_scope403The key lacks the required scope.
Request cURL JavaScript PHP (HTTP) PHP (Internal)
```bash
curl -X POST 'https://panel.example.com/api/v1/client/services/622/password' \
-H "Authorization: Bearer $CLIENT_KEY" \
-H 'Content-Type: application/json' \
-d '{"password":"a-long-new-secret"}'
```
```javascript
const res = await fetch(`https://panel.example.com/api/v1/client/services/${id}/password`, {
method: 'POST',
headers: {
Authorization: `Bearer ${clientKey}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ password }),
});
if (res.status === 422) showRule(await res.json());
```
```php
$ch = curl_init('https://panel.example.com/api/v1/client/services/' . $id . '/password');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $clientKey,
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode(['password' => $new]),
]);
$body = json_decode(curl_exec($ch), true);
curl_close($ch);
```
```php
// The panel password is not THE ACCOUNT password: a change here never touches the customer's sign-in.
$d = Kernel::internal('client:Services/GetServiceDashboard',
['owner_id' => $uid, 'id' => $id])['data'];
if ($d['can_change_password'])
Kernel::internal('client:Services/ChangeServicePassword',
['owner_id' => $uid, 'id' => $id, 'password' => $new]);
```
### Pitfalls
> **These endpoints go live to the panel**
>
> The overview, the tools and the tool data come from **the panel itself** rather than the WISECP database. A slow panel makes a long answer and an unreachable one makes the endpoint fail. Do not call these once per row on a listing screen; call them when the user truly asks.
> **Only declared methods can be called**
>
> The method endpoint takes the methods a module declared **open to the customer**. The breadth of the admin side is absent: creating, suspending and terminating are never reachable here. Read the list from the panel overview.
> **A tool's data shape is no contract**
>
> What a tool endpoint returns is **the module's own output** and can move when the server panel does. An interface bound tightly to the field names breaks on a module update. Read the capabilities from the tool listing and build from those.
> **Restricting access closes two endpoints at once**
>
> Where the operator turns access restriction on for a product, both single sign-on and the panel password change **close**, and the sign-in details drop from the overview. The tools keep working. Read the two flags in the overview rather than treating it as a fault.
> **The sign-on address is not for keeping**
>
> The single sign-on address is **short-lived and single use**. Keeping it somewhere and opening it later does not work, and while it lives it carries the right to sign in. Make a new one on each open and write it to no log.
> **The panel password is not the account password**
>
> The password changed here belongs to **the panel on the server** and the customer's WISECP sign-in is untouched. The ability exists on hosting and server services alone, and the module has to support it.
### Related Articles
- [The Services You Own](https://dev.wisecp.com/en/the-services-you-own)
- [Asking for Support](https://dev.wisecp.com/en/asking-for-support)
# Integration / Extending WISECP
## Adding Custom Fields
https://dev.wisecp.com/en/adding-custom-fields
Store extra information against a client or a ticket without adding a column.
### Overview
Two engines share the name. Client profile fields live per language in `users_custom_fields` with key/value values; ticket fields in `tickets_custom_fields` on two axes.
Neither needs a schema change: a definition row, and the value lands in a generic store.
### Prerequisites
- An operator account, or a token with the settings and tickets scopes.
- Familiarity with hooks: transformation is done with two filters.
- Installed language codes: **one row per language**, so two languages are two ids.
### Structure
Definition and value are separate; the value row is named `field_` plus the id.
| Table | Holds | Keyed by |
| --- | --- | --- |
| `users_custom_fields` | Language, type, label, options, flags, rank | `id`, one row per language |
| `users_informations` | The value, as text | `owner_id` plus `field_{id}` |
| `tickets_custom_fields` | The ticket field and its department | `id`; label and type in the `_lang` twin |
| `tickets_access_groups` | The reply-side grouping and its field ids | `id`; the relation lives on the group |
The store is untyped text: multi-choice persists comma joined, an empty answer is an empty string.
### Walkthrough
#### Define the Field
1. Create the definition once per language, from Settings or the client-fields API.
2. Choose the type: `text`, `textarea`, `select`, `checkbox`, `radio`; choice types take an `options` list.
3. Set the visibility flags; they are independent booleans and they compose.
4. Note the id the row is given. Your code uses the id, not the label.
#### Read and Write the Value
1. Write with the info helper, keyed by `field_{id}`.
2. Read with the info reader: a name with no row comes back as `null`, never as a missing key.
3. The reader memoises per request; pass the third argument to bypass it after a write.
4. Delete rather than blank when "not answered" is meaningful: only a removed row triggers a fallback.
#### Transform the Value
1. Listen on the save filter: once per `field_*` key, before the write.
2. Listen on the load filter: on every read, after the rows are collected.
3. Keep the two symmetric, or ciphertext ends up on the profile screen.
4. Guard on the field id: both filters fire for **every** custom field.
### Reference
#### Definition Flags
Five of six are integers holding 0 or 1; `status` is a string, and treating it alike reads every field as disabled.
- **status**: `active` or `inactive`; an inactive field appears only in the operator's list.
- **required**: An empty answer feeds the completeness gate.
- **uneditable**: Visible but not writable; the profile save loop skips these fields.
- **client_hidden**: Operator only, and it **overrides the others**: dropped from sign-up, invoice and required.
- **invoice**: Printed on the invoice view; empty values are dropped.
- **signForm**: Asked during registration; without it, only reachable from the profile screen.
#### The Value Helper
```php
// Upsert. $values is a map of name => value; a custom field's name is "field_{id}".
// Returns true when at least one row was written.
public static function AddInfo($owner_id = 0, $values = []);
public static function setInfo($owner_id = 0, $values = []); // alias of AddInfo
// Read. $names is an array (a comma separated string is also accepted and split).
// Returns a map with EVERY requested name present; a missing row reads as null.
// $noCache = true skips the per-request memo, which you need right after a write.
public static function getInfo($owner_id = 0, $names = [], $noCache = false): array;
// Remove rows entirely. $name is a single name or an array of names.
public static function deleteInfo($owner_id = 0, $name = ''): int|bool;
// Row id of an existing value, 0 when there is none.
public static function isInfo($owner_id = 0, $name = ''): int;
// Reverse lookup: which members hold this value. $first = true returns one row.
public static function findInfo($name = '', $value = '', $first = true): array;
// The completeness gate. Returns [field key => label] for everything still empty;
// an empty array means the account may use the client area.
public static function missing_required_fields($id = 0): array;
```
- **User::AddInfo()**: One row per entry. `phone` and `company_name` mirror onto the member record.
- **User::getInfo()**: Memoised per request, storing the **raw** value, so the load filter still runs.
- **User::missing_required_fields()**: Admin required fields plus the built-in ones, per language.
- **Order trap: findInfo()**: It takes the **name first, value second**: it searches across members. A member id there returns an empty array.
- **Value shape**: All text. A `checkbox` is comma joined on save; the other four are plain strings.
#### The Two Value Filters
Both fire by reference and are scoped to `field_` keys, so `timezone` never reaches them.
```php
// Fired from User::AddInfo(), immediately before the insert or update.
// $value mixed, by reference. What you leave here is what is stored.
// $field_id int, the definition id parsed out of "field_5".
// $owner_id int, the member the value belongs to.
Hook::add('filter:custom_field.save_value', 10, function (&$value, $field_id, $owner_id) {
// ...
});
// Fired from User::getInfo(), after the rows are collected and before they are returned.
// Same three arguments, same order.
Hook::add('filter:custom_field.load_value', 10, function (&$value, $field_id, $owner_id) {
// ...
});
```
- **filter:custom_field.save_value**: The persistence boundary. Change `$value` in place; the return is not used.
- **filter:custom_field.load_value**: The read boundary: decrypt, format, or inject. By reference; the return is not used.
- **action:client.profile_updated**: Fires after a profile save with the member id, the changed columns and the info map. A key means saved, not changed. The return is ignored.
#### Where the Definitions Are Read
Every client surface applies its own filter, and they deliberately disagree.
| Surface | Reader | Filter it applies |
| --- | --- | --- |
| Account profile | `get_custom_fields()`, account model | active, not hidden, member's language, by rank |
| Registration form | `get_custom_fields()`, sign model | the same, plus `signForm = 1` |
| Invoice view | `invoice_custom_fields()` | `invoice = 1`; empty values dropped |
| Validation of one field | `get_custom_field()` | the list filter, on one id |
| Operator surfaces | `get_custom_fields()`, users model | language only; hidden included |
#### Ticket Fields and Their Two Axes
One definition table, two composers; the two memberships live in different places.
```php
// Department axis, used by the ticket CREATE form. $did = 0 returns every field.
// Rows carry the localized name, description, type, properties and options, plus
// department_name. Ordered by did DESC, then rank ASC.
public static function custom_fields($lang = '', $did = 0, $status = '');
// Access-group axis, used by the REPLY composer's credential rows. Reads the group's
// own comma separated list of field ids and returns them IN THAT ORDER, which is the
// drag-and-drop order the operator set. An empty group returns [].
public static function custom_fields_by_group($lang = '', $groupId = 0, $status = 'active');
// The groups themselves, for building the selector.
public static function access_groups($lang = '', $status = 'active');
public static function get_access_group($id = 0, $lang = '', $select = '');
```
- **Tickets::custom_fields()**: Department axis. An empty `$status` returns inactive definitions too.
- **Tickets::custom_fields_by_group()**: Access-group axis; values are encrypted under their own key namespace and shown masked.
- **filter:ticket.custom_fields**: Filters the department-axis list (language, department, status). By reference, return not used.
- **filter:ticket.access_group_fields**: The same for the access-group list; the return is not used.
- **Ticket field types**: text, textarea, number, password, select, radio, checkbox. A `password` skips the sanitiser.
#### Over the API
| Endpoint | What it does | Note |
| --- | --- | --- |
| `GET /settings/client-fields` | Lists definitions | Language is a parameter |
| `POST /settings/client-fields` | Creates one definition | Two languages, two calls |
| `PATCH /settings/client-fields/{id}` | Updates one definition | Not partial for flags: an omitted flag becomes 0 |
| `PUT /settings/client-fields/order` | Reorders the list | Rank drives the display order |
| `GET /tickets/custom-fields` | Lists ticket definitions | Separate engine and scope |
### Example
A field whose value must never sit in the database in the clear.
```php
// The definition ids of the same logical field in each installed language. A client
// field is one row per language, so a single label maps to several ids.
const ACME_TAX_FIELD_IDS = [11, 12];
Hook::add('filter:custom_field.save_value', 10, function (&$value, $field_id, $owner_id) {
if (!in_array($field_id, ACME_TAX_FIELD_IDS, true)) return;
$value = trim((string) $value);
if ($value === '') return; // an empty answer stays empty
$value = Crypt::encode($value, Config::get('crypt/system') . '_ACME_TAX');
});
Hook::add('filter:custom_field.load_value', 10, function (&$value, $field_id, $owner_id) {
if (!in_array($field_id, ACME_TAX_FIELD_IDS, true)) return;
if ((string) $value === '') return;
// decode() returns false on a value that was written before this listener existed,
// so the original text is kept rather than blanking the member's answer.
$plain = Crypt::decode((string) $value, Config::get('crypt/system') . '_ACME_TAX');
if ($plain !== false) $value = $plain;
});
```
The reading side of the same contract; nothing downstream knows the value was encrypted.
```php
$uid = 42;
// Ask for the names you want. Every name comes back, missing rows as null.
$info = User::getInfo($uid, ['field_11', 'gsm']);
$tax = (string) ($info['field_11'] ?? '');
// A multi-choice field is one comma joined string; split it back yourself.
$picked = array_values(array_filter(explode(',', (string) ($info['field_12'] ?? ''))));
// Write. The same names, the same "field_{id}" convention.
User::setInfo($uid, ['field_11' => 'GB123456789']);
// The reader memoises per request, so re-read with the third argument after a write.
$fresh = User::getInfo($uid, ['field_11'], true);
// Removing a row is not the same as writing an empty string: only the removal makes
// the account look like one that never answered.
if ($tax === '') User::deleteInfo($uid, ['field_11']);
```
The operator side, when your module ships its own field: one definition per language at install, and keep the ids.
```php
$ids = [];
foreach (['en' => 'VAT Number', 'tr' => 'Vergi Numarası'] as $lang => $label) {
$ids[$lang] = WDB::insert('users_custom_fields', [
'lang' => $lang,
'type' => 'text', // text | textarea | select | checkbox | radio
'name' => $label,
'status' => 'active', // STRING, unlike every flag below
'required' => 0,
'uneditable' => 0,
'client_hidden' => 0,
'invoice' => 1,
'signForm' => 1,
'options' => '', // comma separated, for select/checkbox/radio
'rank' => 90,
]) ? WDB::lastID() : 0;
}
// Keep the ids: they are the only stable handle to the field, and they differ per language.
Config::setd('acme_vat_field_ids', Utility::jencode($ids));
```
### Pitfalls
> **A field is one row per language, and the ids differ**
>
> No shared parent id joins the language variants, so hiding one leaves the other visible. Collect the ids as a set.
> **Hidden plus required would lock the member out**
>
> The gate redirects until every required field is answered, so required lookups exclude hidden fields.
> **The singular lookup is what refuses the write**
>
> A field left out of the list is a UI decision a forged post ignores; the singular reader is what refuses the write.
> **Adding a flag touches eight places, not one**
>
> A new flag needs the column, the write path, the form and its JavaScript branches, the list column, the locale keys, both API directions and every client surface.
> **The invoice reader returns no ids**
>
> It returns name and value pairs and drops empty values, so a lookup by id reports missing.
### Related Articles
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
- [Changing the Database Schema](https://dev.wisecp.com/en/changing-the-database-schema)
- [Domain Helpers](https://dev.wisecp.com/en/domain-helpers)
- [Adding a Custom Operation](https://dev.wisecp.com/en/adding-a-custom-operation)
- [Working Without Touching the Core](https://dev.wisecp.com/en/working-without-touching-the-core)
## Adding a Scheduled Task
https://dev.wisecp.com/en/adding-a-scheduled-task
Run your own code on a schedule: a handler class in the queue, with retries and telemetry.
### Overview
Scheduled work is a queue, not a crontab. A scheduler picks due tasks, each becomes a row in `cronjob_queue`, and a handler turns that row into work.
A task splits in two: discovery dispatches one job per target, execute does the work for one. Retries are per target.
### Prerequisites
- A running worker; nothing runs until the tick reaches this system.
- Where the handler lives: the core cron directory, or the module that owns it.
- A stable target identifier; it becomes the idempotency key against duplicates.
### Structure
One class per file, named after the class.
| Piece | Where | Rule |
| --- | --- | --- |
| Handler class | `coremio/cronjobs`, `WISECP\CronJobs` | Execute has no suffix, discovery ends in `Discover` |
| Registration | `coremio/cronjobs/registry.php` | Auto-discovery; a class declaring `TYPE` is registered |
| Queue rows | `cronjob_queue` | One row per job: payload, attempts, logs, result |
| Schedule state | `cronjob_runtime` | Per task: last run, next run, last slot, disable switch |
| Task settings | `coremio/configuration/cronjobs.php` | `cronjobs/tasks/{task}`: type minus stage suffix, dots as hyphens |
### Walkthrough
#### Write the Handler
1. One file per class in the cron directory, named after the class.
2. Declare `TYPE`: a dotted string ending in `discover` or `execute`.
3. Add `FREQUENCY` only to the handler the scheduler should trigger.
4. Implement the one interface method: a boolean, or the rich array.
#### Register It
1. Nothing more for a core task; the registry scans the directory.
2. A module task registers from the module's own hook file.
3. Include the file yourself: the autoloader maps only the core cron namespace.
4. List the registered handlers and confirm your type appears.
#### Dispatch the Work
1. In discovery, query targets and dispatch one execute job each.
2. Give every dispatch an idempotency key.
3. Pass the parent job id so children link to the scan, and cap the batch.
4. Snapshot into the payload anything shown later.
#### Verify the Run
1. Open the automation dashboard and use the manual run control.
2. Read the queue row: status, attempts, error log, result payload.
3. If nothing appears, check the tick first: a scan with no work leaves no row.
4. Add a summary formatter once the result payload has settled.
### Reference
#### The Handler Contract
```php
namespace WISECP\CronJobs;
interface CronJobHandler
{
// $payload the decoded array given to dispatch() for THIS job
// $job the whole queue row: id, type, attempts, max_attempts, parent_id,
// idempotency_key, started_at, process_logs and the rest
public function handle(array $payload, array $job): bool|array;
}
```
```php
// MANDATORY. Without it the class is not a task and the registry skips it.
// Last segment is the stage: '.discover' for a scan, '.execute' for atomic work.
public const TYPE = 'acme.sync.discover';
// OPTIONAL, and it means "the scheduler triggers this one directly".
// One of: 'minute' | 'hour' | 'day' | 'month'. An operator can override it per task.
public const FREQUENCY = 'hour';
// OPTIONAL, default 3. Retry budget; the delay is 2 to the power of the attempt,
// in minutes, so 2, 4, 8. Set 1 when a retry would repeat an external side effect.
public const MAX_ATTEMPTS = 1;
// OPTIONAL, default 120. Seconds before the worker aborts this job with an alarm.
// Raise it for long jobs such as a backup; the worker kills the job, not the tick.
public const MAX_RUNTIME = 300;
```
- **WISECP\CronJobs\CronJobHandler**: One method. Without it the registry skips the class.
- **CronScheduler::tick()**: Dispatches handlers whose slot has arrived; safe from several workers.
- **register:cronjobs**: Where a module registers its own types; the return is ignored.
#### What Your Return Means
| Return | Row becomes | Use it when |
| --- | --- | --- |
| `true` | `completed`, no telemetry | Success with nothing worth showing |
| `false` | Retry with backoff, then `failed` | Failure that a repeat might fix |
| A thrown `Throwable` | Identical to `false`, message captured | You do not want to swallow it |
| `['success' => bool, 'result' => array]` | `completed` or `failed`, result stored | You want telemetry |
| `['success' => true, 'status' => 'cancelled', 'result' => array]` | `cancelled`; childless rows deleted | No work this tick |
- **Cancelled, not a log line**: A no-work tick returns the cancelled signal instead of a log entry.
- **result.reason**: A short machine-readable string: `no-targets`, `disabled`, `already-exists`.
- **Failure message**: A throw stores its message in the process log. On bare `false` the queue reads `error`, `gateway_error` or `message`.
- **Stage and counters**: Throughput counts only `.execute`, so a scan is always `.discover`.
#### The Queue Helper
```php
// Enqueue. Returns the new row id, or the EXISTING row id when the idempotency
// key is already taken. A return value greater than zero is not proof of an insert.
public static function dispatch(string $type, array $payload = [], array $opts = []): int;
// Registration. Called for you by the registry for core handlers; a module calls it itself.
public static function register(string $type, string $handlerClass): void;
// Run one claimed row. $job is the full queue row, not an id.
public static function process(array $job): bool;
// Introspection.
public static function resolve_handler(string $type): ?string;
public static function registered_handlers(): array;
public static function resolve_task_type(string $task): string;
// Housekeeping, both already wired into the platform's own tasks.
public static function recover_stale(int $minutes = 5): void;
public static function cleanup(array $retention = []): array;
```
- **CronJobQueue::dispatch()**: Third argument is the options below; the payload is JSON encoded, no objects.
- **opts.idempotency_key**: Unique across the table; present already means no insert, old id returned.
- **opts.parent_id**: Links an execute job to its discovery job; deleting the parent cascades.
- **opts.priority**: Integer, default 5, lower first; equal priorities run oldest first.
- **opts.scheduled_at**: Holds the job until a future moment; null means the next tick.
- **opts.title**: The queue-list label, 255 characters, stored rather than resolved later.
- **opts.max_attempts**: Overrides the handler constant for this dispatch; without either, 3.
- **CronJobQueue::resolve_task_type()**: Turns a task name into a handler type; never swap hyphens for dots.
#### The Results Tab
Built on demand from a static method on your handler; no HTML is stored.
```php
// $resultPayload is exactly the 'result' array your handle() returned.
// Called only when the admin opens the tab, resolved through the registry.
public static function renderSummary(array $resultPayload): string;
```
- **Read the payload, never the database**: The row is historical; current state shows today under yesterday's date.
- **Labels come from the language files**: Write both language files; a missing key should show as the key.
- **Escape everything you print**: The payload holds user and remote text; the formatter returns raw markup.
### Example
A complete pair: the hourly scan, and the worker that reconciles one service.
```php
namespace WISECP\CronJobs;
class AcmeQuotaSyncDiscover implements CronJobHandler
{
public const TYPE = 'acme.quotasync.discover';
public const FREQUENCY = 'hour';
private const BATCH = 200;
public function handle(array $payload, array $job): bool|array
{
// The operator switch. Reading it on the first line keeps a disabled task
// from doing anything at all, which is required for destructive tasks.
if ((int) (\Config::get('cronjobs/tasks/acme-quotasync/enabled') ?? 0) !== 1)
return ['success' => true, 'status' => 'cancelled', 'result' => ['reason' => 'disabled']];
$stmt = \WDB::select('id,name,owner_id')->from('users_products');
$stmt->where('status', '=', 'active', '&&');
$stmt->where('module', '=', 'AcmeCloud');
$stmt->limit(self::BATCH);
$rows = $stmt->build() ? $stmt->fetch_assoc() : [];
if (!$rows)
return ['success' => true, 'status' => 'cancelled', 'result' => ['reason' => 'no-targets']];
$parentId = (int) ($job['id'] ?? 0);
$dispatched = [];
foreach ($rows as $row) {
$sid = (int) ($row['id'] ?? 0);
if ($sid <= 0) continue;
// The key carries the hour slot as well as the service: a fixed key would
// still exist next hour (completed rows keep theirs until retention runs)
// and every later dispatch would silently return the old row instead.
$key = 'acmeq_' . $sid . '_' . date('YmdH');
$childId = \CronJobQueue::dispatch(self::stage_execute(), [
'service_id' => $sid,
'service_label' => trim((string) ($row['name'] ?? '')),
'owner_id' => (int) ($row['owner_id'] ?? 0),
], ['idempotency_key' => $key, 'parent_id' => $parentId]);
$dispatched[] = ['service_id' => $sid, 'child_job_id' => $childId ?: null];
}
return ['success' => true, 'result' => ['items' => $dispatched, 'count' => count($dispatched)]];
}
private static function stage_execute(): string
{
return AcmeQuotaSync::TYPE;
}
}
```
```php
namespace WISECP\CronJobs;
class AcmeQuotaSync implements CronJobHandler
{
// No FREQUENCY: this one is never scheduled, only dispatched by the scan above.
public const TYPE = 'acme.quotasync.execute';
public const MAX_ATTEMPTS = 2;
public function handle(array $payload, array $job): bool|array
{
$sid = (int) ($payload['service_id'] ?? 0);
if ($sid <= 0) return false; // a payload this broken will not fix itself
$service = \Services::get($sid);
if (!$service)
return ['success' => true, 'status' => 'cancelled', 'result' => ['reason' => 'service-gone', 'service_id' => $sid]];
$remote = \Modules::getInstance('Servers', 'AcmeCloud')->quota_of($sid);
$before = (int) ($service['options']['quota'] ?? 0);
$after = (int) ($remote['quota'] ?? 0);
if ($before === $after)
return ['success' => true, 'status' => 'cancelled', 'result' => ['reason' => 'in-sync', 'service_id' => $sid]];
// Options round-trip through Services::set(), which JSON encodes the array
// for you. There is no set_options() helper: read, merge, write the whole map.
$options = $service['options'] ?? [];
$options['quota'] = $after;
\Services::set($sid, ['options' => $options]);
// Everything renderSummary() will need is snapshotted here, while it is true.
return ['success' => true, 'result' => [
'service_id' => $sid,
'service_label' => (string) ($payload['service_label'] ?? ''),
'quota_before' => $before,
'quota_after' => $after,
]];
}
public static function renderSummary(array $r): string
{
$esc = static fn (string $s): string => htmlspecialchars($s, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$L = static fn (string $k): string => (string) \Language::gc('admin/automation/' . $k);
$sid = (int) ($r['service_id'] ?? 0);
$href = (string) \LinkGenerator::admin('services-1', ['detail'], '', ['id' => $sid]);
$name = trim((string) ($r['service_label'] ?? ''));
return ''
. '' . $esc($L('telemetry-acme-service')) . ' '
. ''
. $esc($name !== '' ? $name : (string) $sid) . ' ' . $esc($L('telemetry-acme-quota')) . ' '
. '' . (int) ($r['quota_before'] ?? 0) . ' → ' . (int) ($r['quota_after'] ?? 0) . ' '
. ' ';
}
}
```
The same pair inside a module.
```php
use WISECP\Modules\Addons\Acme\CronJobs\QuotaSyncDiscover;
use WISECP\Modules\Addons\Acme\CronJobs\QuotaSyncExecute;
// Fired while the registry loads, after the core handlers are in place.
Hook::add('register:cronjobs', 1, function () {
// Required: the autoloader resolves WISECP\CronJobs, but not a nested
// namespace inside a module directory, so the file is included by hand.
require_once __DIR__ . DS . 'cronjobs' . DS . 'QuotaSyncDiscover.php';
require_once __DIR__ . DS . 'cronjobs' . DS . 'QuotaSyncExecute.php';
CronJobQueue::register(QuotaSyncDiscover::TYPE, QuotaSyncDiscover::class);
CronJobQueue::register(QuotaSyncExecute::TYPE, QuotaSyncExecute::class);
});
```
Driving the queue by hand.
```php
// Is the type registered at all? An unregistered type fails the job, not the boot.
$handler = CronJobQueue::resolve_handler('acme.quotasync.execute');
// Enqueue one job. Mind the return: an existing key gives you the OLD row's id.
$id = CronJobQueue::dispatch('acme.quotasync.execute',
['service_id' => 5001],
['idempotency_key' => 'acmeq_manual_5001', 'priority' => 1]);
// Run it here and now, bypassing the worker. process() wants the ROW, not the id.
$job = CronJobQueue::get($id);
$ok = $job ? CronJobQueue::process($job) : false;
// Read back what the handler reported; this is the Results tab's own source.
$row = CronJobQueue::get($id, 'status,attempts,result_payload');
$result = Utility::jdecode((string) ($row['result_payload'] ?? ''), true) ?: [];
```
### Pitfalls
> **A fixed key stops the second run**
>
> A completed row keeps its key for seven days and returns the old row's id. Put the time slot into the key when a target can legitimately run twice.
> **Destructive tasks ship switched off**
>
> A task that removes records or sends data outside defaults to disabled and checks its own switch first.
> **Empty minutes are not a stopped scheduler**
>
> A childless cancelled row is deleted, so counting queue rows shows gaps. The proof is the schedule state table, not the queue.
> **Long jobs are killed after two minutes**
>
> The worker arms an alarm and aborts the job when it overruns; prefer splitting long work across dispatches.
> **Retry repeats the side effect**
>
> Failure retries three times by default, repeating what the handler already did. Make it idempotent or set the budget to one.
### Related Articles
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
- [Registering Hooks from a Module](https://dev.wisecp.com/en/registering-hooks-from-a-module)
- [Error Handling](https://dev.wisecp.com/en/error-handling)
- [Domain Helpers](https://dev.wisecp.com/en/domain-helpers)
- [Changing Billing Behaviour](https://dev.wisecp.com/en/changing-billing-behaviour)
- [Working Without Touching the Core](https://dev.wisecp.com/en/working-without-touching-the-core)
## Adding a Custom Operation
https://dev.wisecp.com/en/adding-a-custom-operation
Add a POST endpoint that changes data and answers in JSON, without a new route or error format.
### Overview
An operation is a method that changes data and answers in JSON. You post an `operation` parameter to an existing controller: no route to register. The controller dispatches on the name, checks privileges, and turns a throw into an error.
Operations live in traits, mixed in with `use`, so a method reaches the controller's model and helpers.
### Prerequisites
- A controller that already answers your surface, admin or client.
- A privilege key on the operator panel: an empty declaration lets anyone signed in call it.
- A caller: the panel's request helper acts on your `status`, `message` and `redirect` keys.
### Structure
| Piece | Where | What it carries |
| --- | --- | --- |
| The trait | `coremio/operations`, namespace `WISECP\operations` | One public method per operation |
| The controller | `coremio/controllers`, admin or website | `use` for the trait, plus the declaration array |
| The caller | A template, or your own JavaScript | Posts `operation` plus your fields, reads the JSON |
### Walkthrough
#### Write It
1. Add a public method to a trait: one operation-object parameter, returning `bool`.
2. Call the demo guard on the first line if the method writes.
3. Read inputs through the filter helper, never the raw request arrays; a password needs its own sanitiser.
4. Validate by throwing; there is no error return value to build.
5. Return the response through the output helper, from a variable the after hook can replace.
#### Declare It
1. Import the trait and add it with `use` in the controller class.
2. Merge it into the constructor's declaration array, keyed by the posted name.
3. Give it the privileges the surface uses; the check runs first.
4. Confirm the entry point forwards to the dispatcher; a client controller does it explicitly.
#### Call It
1. Post to the controller's own address with `operation` set to your name.
2. Send it as an asynchronous call, or an admin operation refuses it.
3. Standard keys: a message notifies, a redirect navigates, `reload` reloads.
4. Use the request helper's callbacks only for what those keys cannot do.
### Reference
#### The Operation Object
```php
class Operation
{
public ?string $name = ''; // the posted operation name
public static ?string $last = ''; // the last name constructed, per request
// Built by the dispatcher: $properties is the declaration array entry.
public function __construct($name = '', $properties = []);
// Throws on a demonstration system. First line of every mutating operation.
public function demo(): void;
// Fires a hook and normalises the answers. 'before' and 'after' are shorthands
// for the two generic admin-operation filters; any other string is used as-is.
// Returns [] or ['overwrite' => array] or ['output' => mixed].
public function hook(string $name = '', array $vars = []): array;
// Sends the response. An array is JSON encoded with the JSON header set;
// anything else is echoed as-is. Always returns true, so `return $op->output(...)`
// satisfies the bool return type.
public static function output($response): bool;
public static function name(): ?string;
public function assertContext(): void;
public static function resolveContext(): bool;
}
```
- **$operation->demo()**: Only on operations that write; a read-only one must not carry it.
- **Operation::output()**: Sets the JSON content type and runs the API response filter.
- **$operation->hook()**: Passes the controller name, the operation name and your variables. An error status throws.
- **The bool return**: Nothing reads it; it does not signal success.
#### The Declaration Array
```php
$this->operations = array_merge($this->operations, [
// The common shape: posted name => the privileges required to run it.
'save_acme_settings' => ['privileges' => ['SETTINGS_OPERATION']],
// 'method' points the posted name at a differently named method, which is how
// two posted names share one implementation.
'acme_retry' => ['privileges' => ['SETTINGS_OPERATION'], 'method' => 'acme_run'],
// 'allow_navigation' drops the asynchronous-request requirement. Only for
// operations meant to be opened as a URL, such as a file download, and only
// together with a one-time token of the operation's own.
'download_acme_log' => ['privileges' => ['SETTINGS_OPERATION'], 'allow_navigation' => true],
// A client-side operation usually declares no privileges: it gates itself on
// the member session inside the method instead.
'acme_client_action' => [],
]);
```
- **privileges**: An array of keys; the caller needs any one. A refusal is a message, not a redirect.
- **method**: The method actually called; defaults to the posted name.
- **allow_navigation**: Exempts the operation from the transport check. Downloads only, with a token.
- **Undeclared but present**: A method on the controller is dispatchable without a declaration entry, with **no privileges**.
#### What the Dispatcher Does
| Step | Behaviour | On failure |
| --- | --- | --- |
| Name cleanup | Filtered to a route-safe string; `main` goes to not-found | Unknown names are refused |
| Licence check | An active licence; help and polling operations exempt | An error, before privileges |
| Transport check | An asynchronous request with `X-Requested-With: XMLHttpRequest` | HTTP 403 unless navigation is allowed |
| Privilege check | Runs when the declaration lists privileges | Names the missing privilege |
| Your method | Called with a fresh operation object | Any exception becomes `{"status":"error","message":"..."}` |
| Fallback | No declaration and no method: a registration hook gets the name | Its array answer is sent |
- **register:admin.operations**: The last chance to answer an operation nobody claimed; an array return is sent.
- **filter:admin.operation.before**: Fired by the `before` shorthand. A listener returns an array: `error` blocks, `overwrite_vars` replaces variables, `output` answers instead. Empty continues.
- **filter:admin.operation.after**: The `after` shorthand, once the response variable exists. Same return shape, but `error` throws.
- **filter:api.response**: Runs in the output helper on every array response, with the operation name. Exceptions never reach it; changes are by reference, the return ignored.
#### The Response the Caller Reads
| Key | Value | What the panel does |
| --- | --- | --- |
| `status` | `successful` or `error` | Anything but success with a message is an error |
| `message` | Text already translated | A notification, or a toast if the caller asked |
| `redirect` | A URL, or `reload`, or `script` | Navigates, reloads, or evaluates `script`; with a message it waits |
| `redirect_delay` | Milliseconds | Overrides the wait: five seconds with a message, immediate without |
| `successToast` | Boolean | Forces the toast style over the caller's preference |
| `data` | Anything | Nothing automatic; your own callback reads it |
### Example
An operation that rotates an integration key, and the code that calls it.
```php
namespace WISECP\operations;
use Operation;
use Filter;
use Exception;
trait AcmeSettings
{
public function rotate_acme_key(Operation $operation): bool
{
/** @var \WISECP\controllers\admin\settings $this */
// 1. Refuse on a demonstration system, before anything is read.
$operation->demo();
// 2. Read input. Never $_POST: the filter type is chosen per field, and a
// secret must go through 'password' so its punctuation survives intact.
$id = (int) Filter::init('POST/id', 'numbers');
$label = (string) Filter::init('POST/label', 'hclear');
$confirm = (string) Filter::init('POST/confirm_password', 'password');
// 3. BEFORE HOOKS: after reading, before validating, so a listener can
// substitute the inputs or answer instead of us.
# BEFORE HOOKS
$hook = $operation->hook('before', get_defined_vars());
if ($hook && $hook['overwrite'] ?? []) extract($hook['overwrite']);
if ($hook && $hook['output'] ?? false) return $operation->output($hook['output']);
// 4. Validate by throwing. The dispatcher turns each of these into
// {"status":"error","message":"..."} with no work on your side.
if (!$id) throw new Exception(\Language::gc('admin/settings/error-missing-id'));
if ($label === '') throw new Exception(\Language::gc('admin/settings/error-label-empty'));
$adata = \UserManager::LoginData('admin');
if (!\User::_password_verify('admin', $confirm, $adata['password']))
throw new Exception(\Language::g('needs/permission-delete-item-invalid-password'));
// 5. The work itself, through the model the trait inherits from the controller.
$key = \Utility::generate_hash(48);
$this->model->set_acme_credentials($id, ['label' => $label, 'api_key' => $key]);
// 6. Audit trail. The third argument is a key in the actions language file.
\User::addAction((int) $adata['id'], 'alteration', 'changed-acme-key', ['id' => $id]);
// 7. The response goes into a variable so the after hook can replace it.
$response = [
'status' => 'successful',
'message' => \Language::gc('admin/settings/success-acme-key-rotated'),
'data' => ['masked' => substr($key, 0, 6) . str_repeat('*', 10)],
];
# AFTER HOOKS
$hook = $operation->hook('after', get_defined_vars());
if ($hook && $hook['overwrite'] ?? []) extract($hook['overwrite']);
if ($hook && $hook['output'] ?? false) return $operation->output($hook['output']);
// 8. One exit. output() encodes, sets the header and returns true.
return $operation->output($response);
}
}
```
```php
namespace WISECP\controllers\admin;
use WISECP\operations\AcmeSettings;
use Controllers;
use Filter;
class settings extends Controllers
{
use AcmeSettings;
public function __construct()
{
parent::__construct();
$this->checkLogin();
// Registration and access control in one place. Without the entry the
// method would still be reachable, and it would run unprivileged.
$this->operations = array_merge($this->operations, [
'rotate_acme_key' => ['privileges' => ['SETTINGS_OPERATION']],
]);
}
public function main()
{
// The fork: a posted operation never reaches the page methods below.
if ($operation = Filter::init('REQUEST/operation')) return $this->operation($operation);
// ... page_* dispatch continues here
return '';
}
}
```
The calling side.
```javascript
function rotateAcmeKey(btn) {
WcpRequest(CONTROLLER_LINK, {
method: 'POST',
button: btn, // disabled and given a spinner for the round trip
buttonLoader: saving_loader,
options: { headers: { 'X-Requested-With': 'XMLHttpRequest' } },
data: {
operation: 'rotate_acme_key', // the declared name, exactly
id: ACME_ID,
label: document.getElementById('acmeLabel').value,
confirm_password: document.getElementById('acmeConfirm').value,
},
// status/message/redirect are handled for us; this is only for the extra.
afterDone: (res) => {
if (res.status !== 'successful') return;
document.getElementById('acmeKeyMasked').textContent = res.data.masked;
},
});
}
```
A client-area operation has no generic before and after hook.
```php
namespace WISECP\operations;
use Operation;
use Filter;
use Exception;
trait ClientAcme
{
public function acme_disconnect(Operation $operation): bool
{
$operation->demo();
// Context is resolved INSIDE the operation: the declaration array is
// registration, not a gate, and a method is dispatchable without an entry.
$member = \UserManager::LoginData('member');
if (!$member) throw new Exception(\Language::gc('website/account/err-auth'));
$uid = (int) ($member['id'] ?? 0);
$sid = (int) Filter::init('POST/service_id', 'numbers');
$service = \Services::get($sid);
if (!$service || (int) ($service['owner_id'] ?? 0) !== $uid)
throw new Exception(\Language::gc('website/account/err-not-found'));
// Your own domain hooks, at the point where they belong. A gate refuses by
// returning a non-empty reason, and the operation turns that into an error.
// Both names live in your module's namespace: never fire a core hook, and
// never invent one that the catalogue does not carry.
foreach (\Hook::run('gate:service.acme_disconnect', $sid, $uid) as $veto)
if ($veto) throw new Exception((string) $veto);
// There is no set_options() helper. Options round-trip through Services::set(),
// which JSON encodes the array for you, so read, merge, write the whole map.
$options = $service['options'] ?? [];
$options['acme_linked'] = 0;
\Services::set($sid, ['options' => $options]);
\Hook::run('action:service.acme_disconnected', $sid, $uid);
return $operation->output([
'status' => 'successful',
'message' => \Language::gc('website/account/acme-disconnected'),
]);
}
}
```
### Pitfalls
> **A public method is already an endpoint**
>
> Dispatch accepts any name matching a declaration entry or an existing method, so keep helpers private.
> **The API needs the same rule**
>
> API resources reach the helper or the model directly, so a rule added only to an operation stays bypassable over the token.
> **Encoding by hand skips the output filter**
>
> Echoing your own encoding bypasses the response filter and its flags. Return through the output helper, hook branches included.
> **An operation is not reachable as a link**
>
> An admin operation is refused unless the request identifies itself as an asynchronous call. For a download, declare the exemption and add a one-time token.
> **The demo guard belongs only on writes**
>
> On a listing or a preview it breaks the demonstration system for nothing. If the method writes, the guard is its first line.
### Related Articles
- [Operations](https://dev.wisecp.com/en/operations)
- [Controllers and Routing](https://dev.wisecp.com/en/controllers-and-routing)
- [Filtering User Input](https://dev.wisecp.com/en/filtering-user-input)
- [Admin JavaScript Library](https://dev.wisecp.com/en/admin-javascript-library)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
- [Security Practices](https://dev.wisecp.com/en/security-practices)
## Overriding Text and Templates
https://dev.wisecp.com/en/overriding-text-and-templates
Change a shipped wording or piece of markup, in a way the next upgrade will not undo.
### Overview
Every visible string comes out of a language file and every screen out of a template. Editing those works until the next version overwrites them.
Four seams: a translation filter for one string, the theme content layer for website copy. Then a variables filter for what a template gets, injection points for what it prints.
### Prerequisites
- The exact key; the same word appears in several packages.
- Somewhere for a listener: the hooks directory or your module.
- The installed language list, which is a directory listing.
### Structure
Four stores hold text, each with its own accessor. The wrong one fails silently.
| Store | Path | Read with |
| --- | --- | --- |
| Root packages: needs, date, errors, actions, constants, blocks, routes | `coremio/locale/{lang}/{name}.php` | `Language::g()` |
| Controller packages, one per surface | `coremio/locale/{lang}/cm/{admin\|website\|system}/{name}.php` | `Language::gc()` |
| Module strings | `coremio/modules/{Type}/{Name}/lang/{lang}.php` | `$this->lang['key']` |
| Theme strings and page copy | `templates/website/{Theme}/locale/{lang}.php` | `Language::gc("theme/key")` or the theme's accessor |
Panel edits go to `content/{lang}/{scope}.php` and win. An upgrade replaces `locale/`, never `content/`.
### Walkthrough
#### Find the Key
1. Decide the store from the screen.
2. Search the language directory for the visible text.
3. Confirm on the command line.
4. Note the language: one says nothing about the others.
#### Override an Existing String
1. For a controller string, listen on the translation filter and rewrite the value in place.
2. Keep the listener cheap: it runs on every controller string.
3. For website copy, use the theme's content layer.
4. The filter does not reach root package strings. Change those at the point of use.
#### Add a New String
1. Pick the surface's package and match the neighbours' shape.
2. Add it to **every** installed language; a missing key shows nothing.
3. Nest the array when the key contains a slash.
4. Never hardcode a visible string.
#### Override a Template
1. Decide: what the template *receives*, or what it *prints*.
2. To change the data, filter the variables.
3. To change the markup, use the nearest injection point.
4. To replace a public page, copy the view into your theme.
### Reference
#### The Accessors
```php
// Root packages. $key is "{file}/{key}/{subkey}", one slash per array level.
// Returns false when any segment is missing. There is NO language fallback.
public static function g($key = '', $replaces = [], $slang = ''): array|string|int|bool;
// Controller packages under cm/. Same shape, one extra leading segment for the area.
public static function gc($name = '', $replaces = [], $slang = ''): array|string|int|bool;
// The active language code, for instance "en".
public static function selected(): string;
// Machine value to human label. $dictionary is the locale prefix the value is
// appended to ("admin/orders/status-"), '@toggle', or '@list:{prefix}'.
// An unknown value falls back to itself rather than to an empty string.
public static function enum_label($value = '', $dictionary = '', $slang = ''): string;
// Writes one package file. See the warning below: this REPLACES, it does not merge.
public static function save($key = '', $data = [], $lk = ''): int|bool;
```
- **Language::g()**: Root packages only; a controller key returns `false`.
- **Language::gc()**: Controller packages only. A root package name can return an **empty array**, which passes a truthiness guard.
- **Argument order**: Both static accessors take replacements second, language third. The instance methods disagree.
- **Language::enum_label()**: Turns a stored status into a label. Audit rows keep the raw value.
#### What a Key May Look Like
```php
'Services',
// With placeholders. Two notations exist and both are literal search targets:
// the replacement map's keys are matched as written, braces and colons included.
'welcome' => 'Hello {name}, you have {count} messages.',
'meta-title' => 'Service detail - :name',
// Declared form. g()/gc() return the 'content' string; 'variables' is metadata
// for the translation tooling and never reaches the screen.
'quota-warning' => [
'content' => 'Only {left} of {total} remaining.',
'variables' => '{left},{total}',
],
// A slash in a key is DEPTH, not part of the name. This is the only way to
// make Language::gc('admin/services/labels/renew') resolve.
'labels' => [
'renew' => 'Renew',
'suspend' => 'Suspend',
],
];
```
- **A missing key**: Resolves to `false`, with no language fallback and nothing in the log.
- **Placeholder substitution**: Plain textual replacement. Pass the keys exactly as they appear, braces or colon included.
- **The site address token**: Controller strings get one free substitution: `{SITE-URL}` becomes the base address.
#### The Four Seams
- **filter:i18n.translation**: Fires on every **controller-package** string, by reference. Arguments: value, key, language. Root packages and missing keys never reach it; the return value is unused.
- **filter:template.variables**: Fires for every template, before extraction. Arguments: template path and data array. Returning an array **replaces** the data wholesale, so return all of it.
- **The theme content layer**: Files under `content` override matching keys in `locale`. Written from the panel.
- **ui: injection points**: Several hundred positions print whatever their listeners return, unescaped. This is the panel's stylesheet slot.
- **ui:client.head.css**: The public-site twin of the row above: a stylesheet here restyles a theme. Return the markup; a non-string return is discarded.
- **filter:i18n.translation_save**: Filters what the operator types in the translation editor. Values arrive by reference and the return value is unused.
#### How a Theme Resolves a String
```php
// One string, with optional placeholder substitution.
public function lang(string $key, array $vars = []): string;
// The content editor's own surface, for a module that wants to read or write it.
public static function contentScopes(string $themeName): array;
public static function scopeDefaults(string $themeName, string $lang, string $scope): array;
public static function scopeOverrides(string $themeName, string $lang, string $scope): array;
public static function writeScopeOverrides(string $themeName, string $lang, string $scope, array $values): bool;
```
| Order | Source | Note |
| --- | --- | --- |
| 1 | The operator's override | Wins over all below |
| 2 | The theme's own text | `locale/{lang}.php` plus `locale/{lang}/{scope}.php` |
| 3 | The same key in English | The only language fallback |
| 4 | The core packages, controller first then root | Lets a theme reuse a platform string |
| 5 | The key itself | Never blank, unlike the core accessors |
A scope is `common` or a view path, and only the active one is loaded. A view under `page` drops that prefix.
#### Writing a Package File
> **The writer replaces the file, it does not merge**
>
> The array you hand it becomes the whole file. Paired with an accessor that answers with an empty array, a read-modify-write cycle can reduce a package to one key.
### Example
Renaming a term without a language file.
```php
// Key => replacement, per language. A map lookup keeps the listener O(1); a
// str_replace over every string in the panel would not be acceptable here.
const ACME_WORDING = [
'en' => [
'admin/services/page-list' => 'Subscriptions',
'admin/services/page-title' => 'Subscription detail',
],
'tr' => [
'admin/services/page-list' => 'Abonelikler',
'admin/services/page-title' => 'Abonelik detayı',
],
];
Hook::add('filter:i18n.translation', 10, function (&$value, $key, $lang) {
// Only controller-package strings arrive here, and only when they resolved
// to a string: a missing key never fires this hook, so a gap cannot be
// filled from here.
$value = ACME_WORDING[$lang][$key] ?? $value;
});
```
Changing what a template receives; the path test narrows it.
```php
Hook::add('filter:template.variables', 10, function ($template_path, $data) {
// Normalise: the path arrives with the platform's directory separator.
$path = str_replace('\\', '/', (string) $template_path);
if (!str_ends_with($path, 'admin/services/detail.php')) return null; // not ours
// The return REPLACES $data entirely. Building on the incoming array is not
// a style choice: dropping template_dir or ui_lang breaks the render.
$data['acme_banner'] = Language::gc('admin/services/acme-banner');
return $data;
});
// Markup, at a position the platform announces. The return value is printed
// as-is, so anything variable in it has to be escaped here.
Hook::add('ui:admin.head.css', 10, fn (): string
=> 'Acme
', 'page_title' => 'Acme'];
}
// POST to the same URL with operation=refresh
public function op_refresh(\Operation $operation): bool
{
$operation->demo();
return $operation->output(['status' => 'successful']);
}
}
```
### Pitfalls
> **The operation fallback hook runs outside every wrapper**
>
> A normal operation goes through a wrapper. That wrapper checks the privilege list and refuses a request from outside the panel's AJAX layer. It also builds the object whose demo guard blocks writes in demo mode. The fallback hook is reached only after the wrapper declined, so none of it applies. Check the privilege yourself, in the listener, first.
> **The template variable filter is winner-takes-all**
>
> It is fired by value, and the caller assigns each returned array over the previous one. The last listener that returns an array replaces the entire set; two listeners on the same template do not merge. Read the array you were handed, modify it, and return all of it.
> **A rejected admin area registration is silent**
>
> The registration returns having done nothing in three cases. The class is not a subclass. The namespace does not have the expected shape. The module type is not one of the eleven recognised ones. No exception, no log line, no menu entry. When your page 404s, check the type before the routes.
> **Work done at file scope in hooks.php runs on every request**
>
> The hook loader includes the file whether or not any of your hooks will fire. A database query, a remote call or a full module instantiation outside a listener body is paid on every page load. Load the configuration, check the status, and put everything else inside a closure.
### Related Articles
- [Principles of Upgrade-Safe Work](https://dev.wisecp.com/en/principles-of-upgrade-safe-work)
- [Surviving a Core Upgrade](https://dev.wisecp.com/en/surviving-a-core-upgrade)
- [Writing a Hook Listener](https://dev.wisecp.com/en/writing-a-hook-listener)
- [Registering Hooks from a Module](https://dev.wisecp.com/en/registering-hooks-from-a-module)
- [Adding an Admin Page](https://dev.wisecp.com/en/adding-an-admin-page)
- [Exposing API Endpoints](https://dev.wisecp.com/en/exposing-api-endpoints)
## Surviving a Core Upgrade
https://dev.wisecp.com/en/surviving-a-core-upgrade
What the upgrade run does step by step, what it can take back, and the checks to run before and after.
### Overview
An upgrade is a sequence of steps with a time budget, plus a ledger of everything it overwrote. A health gate sits between the last write and the version stamp.
### Prerequisites
- A second installation you can break. Not the system that serves customers, and not a copy sharing its database.
- A real backup taken before the run, and verified.
- The current version from `coremio/VERSION`, written down before you start.
- [Working Without Touching the Core](https://dev.wisecp.com/en/working-without-touching-the-core): every check below assumes your code sits behind a seam.
### Structure
#### The Run
One version is five steps in a fixed order. A chained upgrade applies each fully and in order, by the code of the version before it.
| Step | What it does | Can it be taken back? |
| --- | --- | --- |
| `backup` | Optional. Database, files and uploads, before anything is touched | Not applicable, it only reads |
| `download` | Fetches the package into the work directory | Yes, nothing outside the work directory changed |
| `extract` | Unpacks it, a batch of entries per slice | Yes, same reason |
| `database` | Runs the release's schema statements once. Already-applied statements are skipped, out-of-order ones are replayed at the end | **No.** Recorded as forward-only and named to the operator |
| `configuration` | Runs the release's configuration script, then merges language files and notification templates | Merges yes, script **no**: arbitrary code cannot be pre-imaged |
| `apply` | Copies the package's files over the system, then the delete manifest, health gate and version stamp | Yes, from the ledger, once |
| `finish` | Sweeps the work directory | Not applicable |
Each step runs until its time budget expires, writes its position into a cursor, and returns. A web request gets sixty percent of the configured execution limit, clamped between 5 and 45 seconds. The command-line slice the minutely cron uses gets 300 seconds. The cron handler stops starting new slices after 1440 seconds of its own 1800 second ceiling.
#### The Pre-Image Ledger
One directory per run under `coremio/storage/updates-preimage`, outside the work directory so it outlives the run. Every overwrite and manifest deletion is copied here first, and the copy kept is the pre-run state.
| Entry | What is in it | What reads it |
| --- | --- | --- |
| `meta.json` | Source version, versions applied, whether it was a re-apply, the state before | The rollback button, deciding whether it can be offered |
| `files/` | The pre-run copy of every file overwritten or deleted | The restore, which copies all of it back |
| `added.list` | Paths the run created that did not exist before | The restore, which deletes them (undoing an addition is a removal) |
| `changed.list` | Files whose contents actually changed, by checksum | The health gate, which lints exactly this list and nothing else |
| `forward.list` | What cannot be undone: the schema migration, the release configuration script | The rollback summary, which names them to the operator |
| `baseline.json`, `gate.json`, `restored.json` | Health before, health after, evidence of a restore | You, when you need to know what the gate saw |
#### The Health Gate
Health is measured twice: a baseline before the first byte of the apply step, then the gate. The verdict is relative, so a broken baseline rolls nothing back.
Three questions are asked, cheapest first. Do the changed PHP files still parse? Does a fresh process boot and reach the database? Does the system answer its own home page?
| Field | Meaning | Effect on the gate |
| --- | --- | --- |
| `errors` | A check ran and failed | Triggers the rollback, and the run fails as a health check failure |
| `skipped` | A check could not run at all | No verdict. Recorded in the evidence file and otherwise ignored |
| `http` | A state, not a boolean: ok, unreachable, or the failure | Compared against the baseline, and asked twice before it is believed |
### Walkthrough
#### Before
1. Write your dependency surface as a file, not as a memory. Every hook name you listen to. Every class and method called from outside your directory. Every core table, column and configuration key you read.
2. Grep your own tree for core paths and confirm you edited none. The ledger restores the previous release, not your version.
3. Check that your module carries a `manifest.json` if it is meant to be updatable. Without one the updater never touches the directory.
4. Run the whole upgrade on the copy first, from the panel and not only from cron.
#### After
1. Run your compatibility probe before you open a page. Does every class and method you call still exist?
2. Exercise each hook you depend on and confirm your canary recorded a hit. There is no runtime registry of hook names.
3. Read the error log. An exception inside a listener is caught, logged and swallowed, so a broken listener looks like a hook that never fired.
4. Check the configuration keys your code reads. The apply step skips an existing configuration file, and the module updater preserves your `config.php`. New keys are never created for you.
5. Re-run your own schema guard if your module owns tables or added columns. The core upgrade knows nothing about them.
6. Tell the operator the rollback window is one run, once.
#### When a Seam Moved
| Symptom | Check | Usually means |
| --- | --- | --- |
| Your listener no longer runs and nothing is logged | Search the hook catalogue for the name, then for a near neighbour of it | The hook was renamed, or its call site was removed. Your registration is still perfectly valid and attached to nothing |
| Your listener runs but the change is ignored | Whether the point is fired by value or by reference | It became by-reference. Your return value is discarded, and the caller wants the argument modified in place |
| Fatal: call to an undefined method | The class in the source, not the log | The name held, the method did not. Guard the call and degrade instead of throwing |
| Too few or too many arguments | The parameters table on the hook's page | The call site's argument list changed. Declare only the parameters you use and give the rest defaults |
| Your admin page returns not found | The module type, before the routes | A silently rejected admin area registration. Or a slug that now collides with a core route |
| It works from cron and dies from the panel | `function_exists('exec')` in both contexts | **Not an upgrade regression.** Shared hosting disables the process functions in the web pool; the command-line binary keeps them |
#### Shipping Your Own Update
1. Put a `manifest.json` in the module or theme directory.
2. Keep the version there and nowhere else. The one inside `config.php` freezes at first install, because an update never writes that file.
3. Never reuse or edit a version number after publishing it. It is the identity every installation compares against.
4. Two things survive on the customer's disk that you did not send. Their `config.php`, skipped wherever one exists. And any file you removed from the package: an update overwrites but never deletes.
5. Write the manifest last in your own tooling too. A half-finished apply must never claim a version that is not fully on disk.
### Reference
#### The Upgrade API
```php
const VERSION_STEPS = ['download', 'extract', 'database', 'configuration', 'apply'];
const PREIMAGE_DIR = 'updates-preimage'; // under coremio/storage/
const PREIMAGE_KEEP = 3; // runs retained, pruned when a new run opens
const LINT_SECONDS = 60.0; // gate lint budget, time not file count
const LINT_MAX_FILES = 2000; // safety brake behind the time budget
const HTTP_SETTLE_SECONDS = 5; // waited before asking, and after restoring
public static function open(array $opts, string $workerId): int;
public static function tick(int $runId, string $workerId): array;
public static function health_probe(): array;
public static function restorable(): array;
public static function restore_last(): array;
public static function parked(array $run): bool;
```
```php
public static function check_state(): array;
public static function check_new_version(): array;
public static function next_versions(string|int $ver = 0): array;
public static function run_active(string $kind = 'core'): array;
public static function last_completed_run(string $kind = 'core'): array;
public static function run_get(int $id): array;
public static function sc_state(): array;
// coremio/helpers/license.php - what the installation currently claims to be.
public static function version($realtime = false): string;
```
- **UpdateRunner::health_probe()**: The same three questions asked outside an upgrade, with an empty changed-file list so the lint pass skips itself. Returns `['ok' => bool, 'errors' => string[], 'skipped' => string[], 'http' => string]`. Use it as the shape your own probe copies.
- **UpdateRunner::restorable()**: Returns the run that can be undone, or an empty array. Empty when a run is active, when there is no completed run, or when the ledger has no metadata. Also when a restore already happened. Rollback is offered once per run.
- **Updates::run_active()**: A non-empty array while an upgrade is in flight. Worth checking at the top of your own scheduled work: a run in progress means the file tree is a mixture.
- **License::version()**: Reads the stamp the runner writes last, so it only reports a version that finished. Compare with `version_compare()`: as text, a two-digit minor sorts below a one-digit one.
#### The Update Manifest
It sits next to the module class, or next to the theme definition rather than replacing it.
```json
{"type":"marketplace","name":"AcmeBilling","version":"1.2.0","last_updated":"2026-07-28"}
```
| Field | Required | What it does |
| --- | --- | --- |
| `type` | Always | Which publisher answers for this directory. An unknown value makes the whole manifest invalid rather than half read |
| `name` | Store products | The product key. The directory name is not used; it is yours to choose |
| `id` | Marketplace listings | The listing identity, for the same reason: two developers can pick the same directory name |
| `version` | Always | The installed version. This and only this drives the comparison |
| `last_updated` | Optional | Shown to the operator. It takes part in no decision |
> **Detection is automatic, installation is not**
>
> The daily task only looks for new versions and notifies the operator. No scheduled task installs an update.
### Example
A compatibility probe your module can ship.
```php
namespace WISECP\Modules\Addons\Acme\Src;
class Compat
{
// The dependency surface, as data. Everything this module touches outside its
// own directory is listed here, so the probe is the list and not a rewrite.
private const NEEDS_METHOD = [
'Checkout::payment_methods',
'Services::get',
'Invoices::create',
];
private const NEEDS_HOOK = [
'filter:order.cart_totals',
'action:order.checkout_completed',
];
private const CORE_MIN = '5.0.0';
private const CORE_MAX = '6.0.0'; // exclusive: a major bump is opt-in, never assumed
/** @return array{ok:bool,errors:string[],skipped:string[],version:string} */
public static function check(): array
{
$errors = $skipped = [];
$core = \License::version();
if (version_compare($core, self::CORE_MIN, '<'))
$errors[] = 'core ' . $core . ' is below the minimum ' . self::CORE_MIN;
if (version_compare($core, self::CORE_MAX, '>='))
$skipped[] = 'core ' . $core . ' is newer than this module was tested against';
foreach (self::NEEDS_METHOD as $ref) {
[$class, $method] = explode('::', $ref, 2);
if (!class_exists($class)) $errors[] = 'missing class: ' . $class;
elseif (!method_exists($class, $method)) $errors[] = 'missing method: ' . $ref;
}
// A capability, not a result. Under FPM these are usually disabled while the
// same server's CLI keeps them, so "cannot ask" must never read as "failed".
if (!function_exists('exec')) $skipped[] = 'subprocess probes (exec unavailable)';
foreach (self::NEEDS_HOOK as $hook)
if (!self::hook_seen($hook)) $skipped[] = 'hook not observed yet: ' . $hook;
return ['ok' => !$errors, 'errors' => $errors, 'skipped' => $skipped, 'version' => $core];
}
/*
* There is no runtime registry of hook NAMES: hooks are fired, not declared, and the
* store is private. So the only honest answer is observational - the canary below
* records a timestamp when the point actually fires, and "not seen" is skipped,
* never an error, because it may simply not have been reached yet.
*/
public static function canary(string $hook): void
{
$seen = (array) \Utility::jdecode((string) \Config::getd('acme_hook_seen'), true);
$seen[$hook] = time();
\Config::setd('acme_hook_seen', \Utility::jencode($seen));
}
private static function hook_seen(string $hook): bool
{
$seen = (array) \Utility::jdecode((string) \Config::getd('acme_hook_seen'), true);
return (int) ($seen[$hook] ?? 0) > 0;
}
}
```
The canary is registered next to the listener it watches, at a priority that puts it first.
```php
use WISECP\Modules\Addons\Acme\Src\Compat;
include_once __DIR__ . DS . 'src' . DS . 'Compat.php';
// Priority 1: ahead of the real listener, so the observation is independent of it.
Hook::add('filter:order.cart_totals', 1, function (&$summary, $items, $subtotal) {
Compat::canary('filter:order.cart_totals');
});
// The gate the module itself sits behind. An incompatible core disables the feature
// instead of throwing inside somebody's checkout.
$acme_compat = Compat::check();
if ($acme_compat['ok']) {
Hook::add('filter:order.cart_totals', 20, function (&$summary, $items, $subtotal) {
// ... the real work
});
}
else {
Hook::add('ui:admin.body.end', 90, function () use ($acme_compat) {
return '';
});
}
```
Two commands worth running by hand on the copy, right after the run.
```bash
# What the gate actually saw, including everything it could not measure.
cat coremio/storage/updates-preimage/*/gate.json
# Errors since the run, where a swallowed listener exception is the only trace.
php coremio/errlog.php list --limit=20
```
### Pitfalls
> **Passes from cron, fatals from the panel**
>
> Shared hosting pools disable the process functions in the web configuration, while the same server's command-line binary keeps them. A disabled function raises an error, not a warning, so the silencing operator does not help. Check the capability before you spawn a subprocess. A missing one is skipped, not failed.
> **Files roll back, the schema does not**
>
> Restoring the ledger puts every overwritten file back and deletes everything the run created. But the migration already moved the schema, and the configuration script already ran. If your module reads a core column, check the column rather than the version number.
> **A half-applied core is a real state**
>
> The file tree can be a mixture of two versions for minutes. Scheduled work started in that window can load one class from the old release and another from the new.
> **Rollback is one run, once, and only the last one**
>
> The button appears only for the most recent completed run, and only while nothing is running. It disappears once used. Anything older needs a full backup.
### Related Articles
- [Principles of Upgrade-Safe Work](https://dev.wisecp.com/en/principles-of-upgrade-safe-work)
- [Working Without Touching the Core](https://dev.wisecp.com/en/working-without-touching-the-core)
- [Shipping Module Updates](https://dev.wisecp.com/en/shipping-module-updates)
- [Packaging a Module for Distribution](https://dev.wisecp.com/en/packaging-a-module-for-distribution)
- [Debugging and Logs](https://dev.wisecp.com/en/debugging-and-logs)
- [Adding a Scheduled Task](https://dev.wisecp.com/en/adding-a-scheduled-task)
## Security Practices
https://dev.wisecp.com/en/security-practices
The security layers this platform provides, and the call that engages each one. Alongside them, three mistakes that have shipped. A permanently open guard, a filter that destroys the value it protects, an upload served as executable markup.
### Overview
Every layer below exists in this codebase, is engaged by one named call, and is enforced at one named place. None is automatic. A controller does not filter its own input, and a public form is not protected until it asks.
Third-party code goes wrong in two of them. Input filtering is per field and per type. Ownership on the client API is per query, not per request.
### Prerequisites
- [Filtering User Input](https://dev.wisecp.com/en/filtering-user-input) for the full filter vocabulary. This article covers the consequences of choosing wrong.
- A surface to secure, and knowledge of who reaches it. An admin operation, a public form, a client endpoint and a module endpoint engage different layers.
- The panel's Security settings open in another tab. Every threshold below is a configuration key. A limit hardcoded into your module ignores the operator's setting.
### Structure
#### The Layers
| Layer | What it stops | Engaged by |
| --- | --- | --- |
| Input filtering | Injection and markup smuggled through a field | **Your code**, one call per field, with the type that matches the field |
| Output encoding | Stored values executing when they are printed back | **Your code** in admin templates and JSON. Website templates escape automatically |
| Privilege check | A signed-in operator doing something their role does not allow | The operation wrapper, from the operation's own declaration. **Your code** when a fallback hook answers instead |
| API scope | A valid credential reaching an endpoint it was not granted | The kernel, unless the route sets the auth-only flag, in which case any valid key passes |
| Owner scope | One client reading another client's rows | **Your code**, in every query, from the injected owner and never from the request body |
| Form guards | Cross-site submission, flooding, bots and spam content | **Your code**, four to five calls in a fixed order, plus two template tags |
### Walkthrough
#### Read Input Safely
1. Never touch a superglobal. Read through the filter helper with a source prefix.
2. Pick the filter type from what the field *is*, not from habit.
3. Filtering is not validating. After the type filter removes what cannot belong, check that the rest is usable.
4. Read every array value with a default and cast it in the same expression. A missing key in a loop is also a log write on every iteration.
5. Write the presence test against `false`, never against `null`.
#### Authorise the Caller
1. In a normal admin operation, declare the privilege list in the operation's own properties. The wrapper checks it before your method runs.
2. In an operation answered by the fallback hook, check the privilege yourself, first in the listener. The wrapper has already declined, so nothing of it applies. Not the privilege list, not the demo-mode guard, not the refusal of non-AJAX requests.
3. On a module API route, choose between a scope and the auth-only flag deliberately. Auth-only lets in any valid credential of the right audience. Sensible for the free surface, not for anything that writes.
4. On any client-facing endpoint, take the identity from the injected owner. An account identifier in the request body is the caller's suggestion, not an answer.
#### Protect a Public Form
1. Print the token tag inside the form element, and the captcha tag where the form can require one.
2. Verify the token first, right after the demo guard. Verification expects the AJAX header by default. A form that posts normally passes the non-AJAX flag as the third argument.
3. Check the hard block, then the captcha requirement. The spam guard comes last, after the fields are read.
4. Count the request at the end, and clear or record the shield window depending on whether a captcha was solved.
5. Add your form to the spam guard's call list. A guest surface that skips it has the four bot layers and none of the content rules.
#### Serve an Uploaded File
1. Stream it through the helper. Never write the content type header yourself from the detected type.
2. Deny direct access to the upload directory with a rule file.
3. Leave image directories meant to be shown inline alone.
4. Verify all three. The static path returns forbidden and the image path still works. The controller forces a download for markup and shows plain text inline.
### Reference
#### Reading Input
```php
// $arg is "SOURCE/key" or "SOURCE/key/subkey"; sources: GET/ POST/ REQUEST/ FILES/ SERVER/
// $mod is the filter type; $special adds characters to the allowed set of some types.
public static function init($arg = NULL, $mod = false, $special = false);
// Raw access to one source. Nested keys with a slash. Absent key => false.
public static function GET($arg = '');
public static function POST($arg = '');
public static function REQUEST($arg = '');
public static function SERVER($arg = '');
// Allowed-tag strip, used by the "hclear" type and callable directly.
public static function html_clear($arg = NULL, $allow = '');
```
| Type | What survives it | Use it for |
| --- | --- | --- |
| `password` | **Everything.** A deliberate pass-through that returns the argument untouched | Secrets of every kind. Any other type deletes the characters that make them strong |
| `hclear` | Text with tags stripped | Free text with no other shape: a note, a subject line, a name |
| `rnumbers` | An integer | Record identifiers, counts, anything you are about to put in a query |
| `numbers` | Digits and the hyphen, as a string | Phone numbers and reference codes, where the leading zero matters |
| `amount`, `rate` | Digits with separators, and a float respectively | Money and percentages. Never the plain text filter, which keeps a stray letter |
| `email` | The address character set only | Addresses, and then a format check on top: the filter removes, it does not validate |
| `ip` | Address characters | Addresses and ranges. Follow it with a real parse before you compare anything |
| `route` | Letters, digits, hyphen, underscore and dot, with parent traversal removed first | Anything that becomes part of a path or a route key |
| `letters_numbers` | Letters and digits, plus whatever the third argument allows | Identifiers you control the shape of: a database name, a module key, a slug |
| `domain` | Alphanumerics, dots and hyphens, lowercased. It does **not** validate: `not a domain!!!` comes back as `notadomain` | Names, and then a real check on top, exactly like the address filter. It also ignores the third argument |
> **An absent key is false, so a guard written against null is always open**
>
> Both the typed reader and the direct source readers return `false` for a missing key. They never return `null`. A not-equal-to-null condition is true on every request, so the branch behind it runs unconditionally. This has shipped. A mode flag guarded that way loaded a simulation layer on every visit. Nothing reached the server while the responses looked successful. Cast to string before comparing with an empty string.
#### Authorising
```php
// coremio/helpers/admin.php - true when the signed-in operator holds the privilege.
public static function isPrivilege($privileges): bool;
// coremio/api/Auth/Scope.php - the credential's grants against the route's requirement.
public function __construct(array $granted);
public function allows(string $required): bool;
// coremio/api/Resources/Client/_ClientResource.php - the client the request acts for.
protected function owner(): int;
protected function assertOwned(mixed $row, string $message = 'Resource not found.'): array;
```
- **Admin::isPrivilege()**: Takes the same array a normal operation declares. There the wrapper calls it for you and refuses before your method runs. In a fallback-hook listener nothing calls it, so you do.
- **Scope::allows()**: Grants are `Group/Action` strings and match three ways. The exact string, the whole group with a trailing wildcard, or a single wildcard meaning everything. An empty requirement passes: an unset route scope is an open route.
- **owner()**: The acting client, injected by the kernel from the credential on an external call and from the input on an internal one. It throws rather than returning zero, so no query silently runs unscoped.
- **assertOwned()**: Turns both "does not exist" and "belongs to somebody else" into the same not-found answer. The distinction is itself information: leaking it lets a caller enumerate which identifiers are real.
#### Guarding a Public Form
Five independent layers, in this order. The first four judge who is asking, the fifth what they sent.
| Order | Call | When it says no |
| --- | --- | --- |
| 1 | `Validation::verify_csrf_token($token, $key, $nonAjax = false)` | Refuse immediately, before any other work. The key must match the one the template printed |
| 2 | `ProcessRestriction::blocked($action)` | This address is inside a hard block window. Answer with the rate-limit message and stop |
| 3 | `Captcha::enabled($area)` or `BotShield::triggered($action)` | A captcha is required. Record the attempt and answer with the captcha-required status |
| 4 | `Validation::spam_guard($subject, $message, $email, $phone, $ip, $domain)` | Non-empty means blocked. The returned reason goes to the log, never to the visitor |
| 5 | `ProcessRestriction::hit($action)` plus shield record or clear | After the real work. Skipping it is why a limit that looks configured never fires |
```php
// coremio/classes/Validation.php
public static function get_csrf_token($form_index = '', $input = true);
public static function verify_csrf_token($incoming_data = '', $form_index = '', $nonAjax = false);
public static function spam_guard(string $subject = '', string $message = '', string $email = '',
string $phone = '', string $ip = '', string $domain = ''): string;
public static function password_chars_error($password = ''): string;
// coremio/helpers/processrestriction.php - null ip means "the caller's", proxy aware.
public static function blocked(string $action, ?string $ip = NULL): bool;
public static function hit(string $action, ?string $ip = NULL): bool;
public static function clear(string $action, ?string $ip = NULL): void;
// coremio/helpers/botshield.php - the adaptive captcha, counted per address.
public static function active(string $action): bool;
public static function triggered(string $action, ?string $ip = NULL): bool;
public static function record(string $action, ?string $ip = NULL): void;
public static function clear(string $action, ?string $ip = NULL): void;
// coremio/helpers/captcha.php - the static setting, and the answer check.
public static function enabled(string $area = ''): bool;
public function check(): bool;
// coremio/classes/FraudModule.php - order time only. Empty string means clean.
public static function run_checks(array $params = []): string;
```
- **spam_guard() returns a reason, not a boolean**: An empty string is clean; anything else is the operator-facing reason, already written to the blocked list. Show the visitor the generic translated message instead. The reason names which rule fired, which is a tuning aid for an attacker.
- **The token key is a literal contract**: The string the template printed and the string the handler verifies must be identical. They are not derived from the route, so a mismatch is not an error you will see. Every submission fails verification, quietly.
- **Thresholds live in configuration**: Attempt counts, windows and block durations are settings the operator owns, in the options file the Security screens write. A number written into your module stopped working the moment the operator changed theirs.
- **Fraud checks are a separate layer**: They run at order creation, before anything is persisted, and they are not the spam guard. A module that throws is treated as a pass and logged, so a provider outage cannot take checkout down.
#### Output and Files
```php
// coremio/classes/Utility.php - the JSON encoder every response goes through.
public static function jencode($string = '', $flags = 0): string|false;
public static function jdecode($string = '', $mode = false);
// coremio/classes/Utility.php - the only supported way to hand a stored file to a browser.
public static function stream_uploaded_file(string $diskPath, string $fileName, array $opt = []): void;
```
- **stream_uploaded_file()**: Serves inline only for a fixed inert set: portable documents, the four raster image types and plain text. Everything else is forced to a download, including markup and vector images. It carries a generic type, a no-sniff header and a sandbox policy. It strips line breaks and quotes from the file name, sends the content and exits.
- **The cache option is for content-addressed URLs only**: The optional third argument overrides the cache policy, for addresses that change when the file changes. A sensitive document must not pass it: the short private default is the point.
- **Utility::jencode()**: Used instead of the raw encoder so every response shares one flag set. That keeps non-Latin characters and slashes readable rather than escaped. Encoding is not escaping: a value printed into markup still needs escaping at the point of print.
- **htmlspecialchars()**: Admin templates are plain PHP with no automatic escaping, so anything you print there escapes at the point of print. Website templates escape by default, the opposite trap: a pre-encoded value stored there is encoded twice and shows the entities on screen.
### Example
A guest form end to end. The template prints the two tags, the handler applies the five layers in order.
```smarty
```
```php
public function submit(\Operation $operation): bool
{
// The wrapper hands every operation an Operation object. Open with the demo guard:
// it throws before a write can happen on a demo system.
$operation->demo();
// 1. Token before any other guard. Third argument true for a non-AJAX post.
if (!\Validation::verify_csrf_token((string) Filter::init('POST/token', 'hclear'), 'acme-request'))
return $operation->output(['status' => 'error', 'message' => Language::g('needs/csrf-failed')]);
// 2. Hard block window for this address.
if (\ProcessRestriction::blocked('acme-request'))
return $operation->output(['status' => 'error', 'message' => Language::gc('acme/too-many')]);
// 3. Captcha: the operator's static setting, OR the adaptive shield having tripped.
$needCaptcha = \Captcha::enabled('acme-request') || \BotShield::triggered('acme-request');
if ($needCaptcha && !(new \Captcha())->check()) {
\BotShield::record('acme-request');
return $operation->output(['status' => 'captcha_required']);
}
// One call per field, and the type is chosen from what the field IS.
// The secret uses the pass-through filter: any text filter would silently delete
// exactly the punctuation that makes a password strong.
$company = Filter::init('POST/company', 'hclear');
$email = Filter::init('POST/email', 'email');
$note = Filter::init('POST/note', 'dtext');
$password = Filter::init('POST/panel_password', 'password');
// Filtering removed what cannot belong; validation decides whether the rest is usable.
if (!filter_var($email, FILTER_VALIDATE_EMAIL))
throw new Exception(Language::gc('acme/email-invalid'));
if ($e = \Validation::password_chars_error($password)) throw new Exception($e);
// 4. Content and sender rules, after the fields are read, before the real work.
if (\Validation::spam_guard('', $note, $email, '', UserManager::GetIP()) !== '')
throw new Exception(Language::g('needs/spam-blocked'));
// ... the real work
// 5. Count this request and settle the shield window.
\ProcessRestriction::hit('acme-request');
if ($needCaptcha) \BotShield::clear('acme-request');
else \BotShield::record('acme-request');
return $operation->output(['status' => 'successful']);
}
```
The other two surfaces, shaped so the guard cannot be skipped.
```php
public function GetNote(array $body = []): array
{
$id = (int) ($body['id'] ?? 0);
// The owner comes from the credential. An account id in the body is a SUGGESTION
// from the caller and is never used to select the account.
$row = WDB::select('*')->from('acme_notes')
->where('id', '=', $id)
->where('owner_id', '=', $this->owner())
->build('assoc');
// Missing and foreign both answer 404: which ids exist is itself information.
return ['data' => $this->assertOwned($row)];
}
public function stream_note_file(int $id): void
{
$row = $this->model->note($id);
if ((int) ($row['owner_id'] ?? 0) !== $this->owner()) { http_response_code(404); exit; }
// Never build these headers by hand from the detected type: an uploaded page
// served inline runs on this origin, against the next operator who opens it.
\Utility::stream_uploaded_file(ROOT_DIR . $row['path'], $row['name']);
}
```
```apache
# The ownership check above lives in PHP; the web server does not know about it and
# will serve the same bytes straight from the path. Reading the file from disk is a
# filesystem operation and is unaffected, only the direct HTTP route is closed.
# Both syntaxes, the way every private upload directory in the tree is already written:
# the 2.4 directive alone is an error on a server without mod_authz_core.
Require all denied
Order allow,deny
Deny from all
```
### Pitfalls
> **A generic sanitiser breaks the secret fields first**
>
> Text filters remove punctuation, and punctuation is what makes a password strong. Run one over a password field and the value is silently shortened. The account is created with something the customer never typed, and shows up later as a login that fails. Filter per field, and give secrets the pass-through type.
> **A web-reachable upload directory has no access control**
>
> Every ownership check in your controller is bypassed by requesting the file's path directly. The server serves an uploaded page as a page. Both halves are required. The stream helper forces the type inert, the deny rule closes the static route.
> **Emptiness tests treat a stored zero as absent**
>
> The emptiness test is true for the string zero. A setting the operator explicitly turned off reads as one that was never configured. The code falls through to its default. Read the key with a default and cast it in the same expression, then compare.
> **Never fetch a URL the caller supplied**
>
> An outbound request to an address the caller chose reveals the origin behind a content network to whoever owns it. Client-facing endpoints take uploaded bytes instead. Fetch a URL only on an operator surface, or from a source the provider signed.
### Related Articles
- [Filtering User Input](https://dev.wisecp.com/en/filtering-user-input)
- [Securing Theme Forms](https://dev.wisecp.com/en/securing-theme-forms)
- [API Authentication and Permissions](https://dev.wisecp.com/en/api-authentication-and-permissions)
- [The Client API](https://dev.wisecp.com/en/client-api-overview)
- [Operations](https://dev.wisecp.com/en/operations)
- [Principles of Upgrade-Safe Work](https://dev.wisecp.com/en/principles-of-upgrade-safe-work)