Orders API
An order is a client’s service: a hosting account, a domain, a licence or a custom product, with its price, billing period and status. These calls manage orders and their life cycle, failed actions, holds, cancellation requests, upgrades and bulk price updates; client calls show a client their own services. See Orders for the user guide.
Admin calls need Module access on the Order card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”POST /api/admin/order/get
Returns one order with everything staff see.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
deep |
boolean | Kept for compatibility; the result is the same. Default true. |
Returns: The order: id, client_id, product_id, form_id, promo_id, promo_code, promo_recurring, promo_renews (the promotion still comes off renewals), promo_used, group_id, group_master (false for an add-on), invoice_option, title, currency, unpaid_invoice_id, service_id, service_type, period, quantity, unit, price, discount, total, status, reason, notes (staff notes), config (the order’s settings and order form answers), referred_by, expires_at, activated_at, suspended_at, unsuspended_at, canceled_at, created_at, updated_at, meta, active_tickets, client (the client’s summary) and auto_suspend_off (Override Auto-Suspend is on now).
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
get_list
Section titled “get_list”POST /api/admin/order/get_list
Lists orders, newest first. Add-ons are left out unless the Orders setting to show them is on.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer | Only this client’s orders. |
status |
string | pending_setup, failed_setup, failed_renew, active, suspended or canceled. |
show_action_required |
boolean | Only orders pending setup, failed setup or failed renewal. |
product_id |
integer | Only orders of this product. |
promo_id |
integer | Only orders with this promotion. |
type |
string | Only this service type, such as hosting or domain. |
title |
string | Text to find in the order title. |
period |
string | Only this billing period, such as 1M or 1Y. |
invoice_option |
string | issue-invoice or no-invoice. |
id |
integer | Only the order with this id. |
ids |
array | Only the orders with these ids. |
search |
string | An order id, or text to find in the client’s first or last name or the order title. |
created_at |
string | Only orders created on this day. |
date_from |
string | Only orders created at or after this date. |
date_to |
string | Only orders created on or before this day (the whole day). |
meta |
object | Only orders with these meta values: an object of name to the value’s beginning. |
active_first |
boolean | With client_id: active orders first. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has the order’s stored fields (id, client_id, product_id, title, status, period, price, quantity, currency, service_type, expires_at and the others of admin/get), config (decoded), total, meta, active_tickets, client (the client’s summary) and auto_suspend_off.
Example
Request parameters:
{ "status": "active", "per_page": 1}result:
{ "pages": 12, "page": 1, "per_page": 1, "total": 12, "list": [ { "id": 31, "client_id": 7, "product_id": 4, "title": "Starter Hosting example.com", "status": "active", "period": "1M", "price": 5, "quantity": 1, "currency": "USD", "service_type": "hosting", "service_id": 12, "group_master": 1, "invoice_option": "issue-invoice", "expires_at": "2026-12-17 10:00:00", "activated_at": "2026-11-17 10:00:00", "created_at": "2026-11-17 09:58:12", "config": { "domain": { "action": "owndomain", "owndomain_sld": "example", "owndomain_tld": ".com" } }, "total": 5, "meta": [], "active_tickets": 0, "client": { "id": 7, "first_name": "Alex", "last_name": "Example", "email": "alex@example.com" }, "auto_suspend_off": false } ]}create
Section titled “create”POST /api/admin/order/create
Creates one order for a client (the classic single-product form), optionally with an invoice and activation.
Permission: Manage orders (order.manage); with mark_invoice_paid, also Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. |
product_id |
integer, required | The product. |
period |
string | The billing period, such as 1M or 1Y. Needed for a recurring product unless you set price. |
quantity |
integer | Default 1. |
price |
number | A price of your own, in the client’s currency. Left out: the product’s price. |
currency |
string | Must be the client’s currency when the client has one. |
title |
string | The order title. Default: the product’s name in the client’s language. |
config |
object | The product type’s settings and order form answers, such as the hosting domain. |
group_id |
string | For an add-on product: the group_id of the main order. |
invoice_option |
string | issue-invoice (issue the first invoice now and renewal invoices on their own) or no-invoice (default). |
activate |
boolean | Activate the order right away. |
skip_validation |
boolean | Skip the product type’s checks of config. |
notes |
string | Staff notes. |
meta |
object | Order meta values to save. |
created_at |
string | Backdates the order. |
draft |
boolean | Leave the invoice a draft for you to check and approve. |
use_credit |
boolean | Pay the invoice from the client’s credit when it covers it. Default true. |
send_email |
boolean | Email the invoice. Default true. |
mark_invoice_paid |
boolean | Mark the invoice paid; needs invoice_option issue-invoice, no draft, and the payment fields of marking an invoice paid (gateway_id, transactionId …). |
Returns: The new order’s id.
Errors:
- Client ID was not passed (code 9999)
- Product ID was not passed (code 9999)
- Client not found (code 9999)
- Product not found (code 9999)
- The order must be in the client’s currency (…). (code 9999)
- Product … is out of stock. (code 831)
- Group ID parameter is missing for addon product order (code 832)
- Choose a billing period this product sells, or set a price. (code 9999)
- Marking an invoice as paid requires the order to issue an invoice. (code 9999)
- A draft invoice cannot be marked as paid. (code 9999)
- Set the auto-suspend override with auto_suspend_override and auto_suspend_until, not in meta. (code 9999)
Fires onBeforeAdminOrderCreate and onAfterAdminOrderCreate. A failed activation is logged and the order stays pending setup. For several products in one order, use admin/create_many.
Example
Request parameters:
{ "client_id": 7, "product_id": 4, "period": "1M", "invoice_option": "issue-invoice", "config": { "domain": { "action": "owndomain", "owndomain_sld": "example", "owndomain_tld": ".com" } }}result:
31POST /api/admin/order/quote
Prices an Add New Order without saving it: the order is made and rolled back, and its totals returned.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. |
items |
array, required | The lines, as in admin/create_many. |
promocode |
string | A promotion code. |
gateway_id |
integer | The payment method, to price its fee. |
Returns: currency, items (each title, quantity, period, price, total, setup_price, discount, due and renewal), promocode, subtotal, discount, tax, tax_name, tax_included, total, credit (the client’s credit), fee, fee_with_credit and fee_title, in the client’s currency.
Errors:
- Client ID was not passed (code 9999)
- Client not found (code 9999)
- Add a product or a domain to the order. (code 9999)
create_many
Section titled “create_many”POST /api/admin/order/create_many
Add New Order: creates one order with several products and domains for a client, priced and checked as at checkout, with one invoice.
Permission: Manage orders (order.manage); with mark_invoice_paid, also Manage invoices (invoice.manage_invoices)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. |
items |
array, required | The lines. Each has product_id (left out: a domain), period, quantity, config (product settings; a domain item’s domain settings; _start_date backdates the line), price and domain_price (your own prices in the client’s currency), and addon_for (an existing order of this client, to add an add-on to it). |
promocode |
string | A promotion code to apply. |
gateway_id |
integer | The payment method of the invoice. |
invoice |
boolean | Make an invoice. Default true. |
activate |
boolean | Activate the orders right away. |
send_email |
boolean | Email the invoice. Default true. |
use_credit |
boolean | Pay from the client’s credit when it covers the total. Default true. |
draft |
boolean | Leave the invoice a draft. |
mark_invoice_paid |
boolean | Mark the invoice paid, with the payment fields of marking an invoice paid. |
Returns: order_ids (the new orders) and invoice_id (or null).
Errors:
- Client ID was not passed (code 9999)
- Client not found (code 9999)
- Add a product or a domain to the order. (code 9999)
- Domains are not sold in this store. (code 9999)
- This promotion code cannot be used for this client. (code 9999)
- The start date … is not a valid date. (code 9999)
- The checkout’s own checks, such as a missing domain or billing period.
Example
Request parameters:
{ "client_id": 7, "items": [ { "product_id": 4, "period": "1Y", "config": { "domain": { "action": "register", "register_sld": "example", "register_tld": ".com", "register_years": 1 } } } ], "send_email": true}result:
{ "order_ids": [ 32, 33 ], "invoice_id": 58}addon_offers
Section titled “addon_offers”POST /api/admin/order/addon_offers
Lists the add-ons an active service can take now (Add Add-on), priced to its due date.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The service’s order id. |
Returns: A list; each has id (the add-on product), title, description, period (the service’s, or null for a one-time add-on), price (each period), setup, now (charged now, for the days left to the service’s due date) and due, in the service’s currency. Empty when the service is not active or has no future due date.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
update
Section titled “update”POST /api/admin/order/update
Changes an order’s details: dates, price, period, title, status, notes and meta. Nothing is sent to the service’s server.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
title |
string | The title. |
price |
number | The recurring price. |
period |
string | The billing period. |
invoice_option |
string | issue-invoice or no-invoice. |
status |
string | Sets the status without running its action (use admin/activate, admin/suspend and the others for that). |
created_at |
string | The created date. |
activated_at |
string | The activation date; the same day keeps the stored time. |
expires_at |
string | The next due date; empty clears it. |
notes |
string | Staff notes. |
reason |
string | The status reason. |
meta |
object | Meta values to set. |
auto_suspend_override |
boolean | Override Auto-Suspend: the cron does not suspend it. false clears it and auto_suspend_until. |
auto_suspend_until |
string | Do not suspend until: YYYY-MM-DD, or empty for no end. |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Invalid order status: … (code 9999)
- Enter the “Do not suspend until” date as YYYY-MM-DD, or leave it blank. (code 9999)
- Set the auto-suspend override with auto_suspend_override and auto_suspend_until, not in meta. (code 9999)
Fires onBeforeAdminOrderUpdate and onAfterAdminOrderUpdate.
Example
Request parameters:
{ "id": 31, "price": 6, "expires_at": "2027-01-17", "auto_suspend_override": true, "auto_suspend_until": "2026-12-31"}result:
truepromo_set
Section titled “promo_set”POST /api/admin/order/promo_set
Sets or removes the recurring promotion that comes off an order’s next renewals. Invoices already issued stay as they are.
Permission: Manage orders (order.manage) and Manage promotions (product.manage_promos)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
promo_id |
integer | A recurring promotion’s id. Empty: remove the promotion (renewals are charged in full unless the client’s automatic promotion applies). |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order not found (code 9999)
- Promo not found (code 9999)
- Only a recurring promotion comes off renewals. (code 9999)
- This promotion code cannot be used for this client. (code 9999)
- This promotion does not apply to the product or billing period of this order. (code 9999)
A new promotion counts a use.
activate
Section titled “activate”POST /api/admin/order/activate
Activates an order pending or failed setup: sets up its service (on the server or registrar) and starts its billing period.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
force |
boolean | Activate again whatever the status. |
Returns: true; also true at once when the order is already active.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Only pending setup or failed orders can be activated (code 9999)
- The server’s or registrar’s own error: the failure is also listed under Failed actions.
Fires onBeforeAdminOrderActivate and onAfterAdminOrderActivate; the client gets the activation email.
POST /api/admin/order/renew
Renews an order: adds a billing period on the service and moves the due date. An order pending or failed setup is activated instead; a paid renewal waiting on an invoice is applied instead.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- The paid renewal could not be applied. The order history has the error. (code 9999)
- The server’s or registrar’s own error.
Fires onBeforeAdminOrderRenew and onAfterAdminOrderRenew. No invoice is made: use it after payment outside ClientFence.
suspend
Section titled “suspend”POST /api/admin/order/suspend
Suspends an active order and its active add-ons, on the server too.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
reason |
string | Why; shown to the client. |
skip_event |
boolean | true fires no events (no email). |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Only active orders can be suspended (code 9999)
- The server’s own error.
Fires onBeforeAdminOrderSuspend and onAfterAdminOrderSuspend (the client gets the suspension email).
unsuspend
Section titled “unsuspend”POST /api/admin/order/unsuspend
Unsuspends a suspended order and the add-ons suspended with it. When a paid renewal waits on an invoice, it is applied instead.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Only suspended orders can be unsuspended (code 9999)
- The server’s own error.
Fires onBeforeAdminOrderUnsuspend and onAfterAdminOrderUnsuspend.
cancel
Section titled “cancel”POST /api/admin/order/cancel
Cancels an active or suspended order with its add-ons, on the server too, and cancels its unpaid invoices. Or, with cancel_at_period_end, schedules the cancellation for the end of the paid period.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
reason |
string | Why. |
cancel_at_period_end |
boolean | Cancel on the due date instead of now (also stops a gateway subscription there). |
skip_event |
boolean | true fires no events. |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Cannot cancel … order (code 9999) for an order canceled, pending or failed setup (delete those instead).
- Only a service billed by period can be cancelled at the end of its period. (code 9999)
- No active gateway subscription is linked to this order. (code 9999)
Fires onBeforeAdminOrderCancel and onAfterAdminOrderCancel.
client_services_action
Section titled “client_services_action”POST /api/admin/order/client_services_action
Suspends, unsuspends or cancels every fitting service of a client at once (main services first; add-ons go with them).
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
client_id |
integer, required | The client. |
action |
string, required | suspend (active services), unsuspend (suspended ones) or cancel (active and suspended). |
reason |
string | For suspend: the reason. |
Returns: done (how many) and failed (each id, title, error).
Errors:
- Client ID was not passed (code 9999)
- Action was not passed (code 9999)
- Unknown action (code 9999)
Example
Request parameters:
{ "client_id": 7, "action": "suspend", "reason": "Unpaid balance"}result:
{ "done": 2, "failed": []}can_cancel_at_period_end
Section titled “can_cancel_at_period_end”POST /api/admin/order/can_cancel_at_period_end
Says whether an order can be cancelled at the end of its period.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: true or false.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
uncancel
Section titled “uncancel”POST /api/admin/order/uncancel
Brings back a canceled order: sets it up on the server again and starts a new billing period from today.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Only canceled orders can be uncanceled (code 9999)
- The server’s own error.
Fires onBeforeAdminOrderUncancel and onAfterAdminOrderUncancel.
delete
Section titled “delete”POST /api/admin/order/delete
Deletes an order: stops its gateway subscription, removes its service from the server, cancels its unpaid invoices and removes the order and its history.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
delete_addons |
boolean | Also delete its add-on orders. |
force_delete |
boolean | Delete it even when the server or gateway step fails. |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- The server’s or gateway’s own error, unless
force_delete.
Fires onBeforeAdminOrderDelete and onAfterAdminOrderDelete. This cannot be undone.
batch_suspend_expired
Section titled “batch_suspend_expired”POST /api/admin/order/batch_suspend_expired
Runs the cron’s step that suspends overdue services now: those past Suspend After Due Date days, and those whose cancellation at the period end is due.
Permission: Manage orders (order.manage)
No parameters.
Returns: true.
Services with Override Auto-Suspend are skipped. The clients get the suspension email.
batch_cancel_suspended
Section titled “batch_cancel_suspended”POST /api/admin/order/batch_cancel_suspended
Runs the cron’s step that cancels services suspended for too long, when that Orders setting is on.
Permission: Manage orders (order.manage)
No parameters.
Returns: true; false when the setting is off.
batch_cancel_unpaid
Section titled “batch_cancel_unpaid”POST /api/admin/order/batch_cancel_unpaid
Runs the cron’s step that cancels new orders left unpaid for too long, when that Orders setting is on.
Permission: Manage orders (order.manage)
No parameters.
Returns: true; false when the setting is off.
update_config
Section titled “update_config”POST /api/admin/order/update_config
Changes an order’s settings (Edit Order Config). With an order form, its answers are checked and replaced; the other settings stay.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
config |
object, required | The settings; with an order form, its full set of answers. |
Returns: true.
Errors:
- Order config not passed (code 9999)
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Field “…” is required (code 4892)
- Invalid value for field “…” (code 4893 or 4894)
service
Section titled “service”POST /api/admin/order/service
Returns the service record behind an order (hosting account, domain, licence…), as its module formats it.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: The service, with the fields its module gives (for hosting: ip, sld, tld, domain, username, reseller, server, hosting_plan, domain_order_id, panel_org_id, panel_subscription_id), or null when the order has no service yet.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
status_history_get_list
Section titled “status_history_get_list”POST /api/admin/order/status_history_get_list
Lists an order’s status history, newest first.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row has id, client_order_id, status, notes, created_at and updated_at.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
status_history_add
Section titled “status_history_add”POST /api/admin/order/status_history_add
Adds a line to an order’s status history. The order’s status does not change.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
status |
string, required | A valid order status, such as active. |
notes |
string | The note. |
Returns: true.
Errors:
- Order status was not passed (code 9999)
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
- Invalid order status: … (code 9999)
status_history_delete
Section titled “status_history_delete”POST /api/admin/order/status_history_delete
Deletes one line of an order’s status history.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The history line’s id. |
Returns: true.
Errors:
- Order history line ID was not passed (code 9999)
- Order history line not found (code 9999)
get_statuses
Section titled “get_statuses”POST /api/admin/order/get_statuses
Counts the orders (main services, not add-ons) per status.
Permission: View orders (order.view)
No parameters.
Returns: total, pending_setup, failed_setup, failed_renew, active, suspended and canceled.
Example
Request parameters:
{}result:
{ "total": 40, "pending_setup": 2, "failed_setup": 0, "failed_renew": 0, "active": 31, "suspended": 1, "canceled": 6}get_invoice_options
Section titled “get_invoice_options”POST /api/admin/order/get_invoice_options
Returns the invoice options of an order, with their translated names.
Permission: View orders (order.view)
No parameters.
Returns: { "issue-invoice": "Automatically Issue Renewal Invoices", "no-invoice": "Issue Invoices Manually" }.
get_status_pairs
Section titled “get_status_pairs”POST /api/admin/order/get_status_pairs
Returns the order statuses staff can choose, with their names.
Permission: View orders (order.view)
No parameters.
Returns: { "pending_setup": "Pending Setup", "failed_setup": "Setup Failed", "active": "Active", "suspended": "Suspended", "canceled": "Canceled" }.
addons
Section titled “addons”POST /api/admin/order/addons
Lists the add-on orders of a service.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The main order’s id. |
Returns: A list of orders with the fields of admin/get.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
batch_delete
Section titled “batch_delete”POST /api/admin/order/batch_delete
Deletes several orders, as admin/delete without force_delete.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
ids |
array, required | The order ids. |
delete_addons |
boolean | Also delete their add-ons. |
Returns: true. It stops at the first order that fails; the ones before stay deleted.
Errors:
- Order IDs were not passed (code 9999)
- Order Not Found (code 9999)
This cannot be undone.
export_csv
Section titled “export_csv”POST /api/admin/order/export_csv
Downloads the orders as a CSV file (orders.csv), not JSON.
Permission: View orders (order.view) and Export orders (order.export)
| Parameter | Type | Description |
|---|---|---|
headers |
array | The columns, from the order’s stored fields (id, client_id, product_id, title, currency, period, price, status, expires_at …). Default: id, client_id, product_id, title, currency, service_type, period, quantity, price, discount, status, reason, notes. |
Returns: The CSV file, every order, one row each.
failed_action_get_list
Section titled “failed_action_get_list”POST /api/admin/order/failed_action_get_list
Lists the failed order actions (Orders → Failed actions): set-ups, renewals, suspensions and the others a server or registrar refused.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
status |
string | open (default), resolved, dismissed or all. |
order_id |
integer | Only this order’s. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 100. Default 25. |
Returns: list, total, page, per_page and pages. Each entry has id, order_id, order_title, order_status, client_id, client_name, action (such as create, renew, suspend, upgrade), message (the last error), attempts, status, first_failed_at, last_failed_at, resolved_at and resolved_by.
Errors:
- Unknown status. (code 9999)
failed_action_retry
Section titled “failed_action_retry”POST /api/admin/order/failed_action_retry
Runs a failed action again; a success closes the entry.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The failed action’s id. |
Returns: true.
Errors:
- Failed action ID was not passed (code 9999)
- Failed action not found. (code 9999)
- This failed action is already closed. (code 9999)
- The order of this failed action no longer exists. Dismiss it instead. (code 9999)
- The order is … now, so this action no longer fits. Dismiss it, or act from the order page. (code 9999)
- This action cannot be retried. (code 9999)
- The server’s own error again.
failed_action_dismiss
Section titled “failed_action_dismiss”POST /api/admin/order/failed_action_dismiss
Closes a failed action without running it again.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The failed action’s id. |
Returns: true.
Errors:
- Failed action ID was not passed (code 9999)
- Failed action not found. (code 9999)
- This failed action is already closed. (code 9999)
upgrade_rule_get
Section titled “upgrade_rule_get”POST /api/admin/order/upgrade_rule_get
Returns whether a product, or one service, allows upgrades and downgrades.
Permission: View orders (order.view) for a service; View products (product.view) for a product
| Parameter | Type | Description |
|---|---|---|
scope |
string, required | order (one service) or product. |
id |
integer, required | The order’s or product’s id. |
Returns: upgrade and downgrade, each allow, block or default (a service follows its product; a product allows).
Errors:
- Scope was not passed (code 9999)
- ID was not passed (code 9999)
- Unknown scope. (code 9999)
upgrade_rule_save
Section titled “upgrade_rule_save”POST /api/admin/order/upgrade_rule_save
Allows or blocks upgrades and downgrades for a product or one service. A service’s rule wins over its product’s.
Permission: Manage orders (order.manage) for a service; Manage products (product.manage_products) for a product
| Parameter | Type | Description |
|---|---|---|
scope |
string, required | order or product. |
id |
integer, required | The order’s or product’s id. |
upgrade |
string, required | allow, block or default. |
downgrade |
string, required | allow, block or default. |
Returns: true.
Errors:
- Scope was not passed (code 9999), and the same for the other fields.
- Unknown scope. (code 9999)
- Unknown product or service. (code 9999)
- Choose allow, block or default. (code 9999)
upgrade_history
Section titled “upgrade_history”POST /api/admin/order/upgrade_history
Lists a service’s last 50 upgrades and downgrades, newest first.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: A list of the stored changes: the old and new product, billing cycle and price, the amount, the invoice, the status (pending, applying, applied, failed, cancelled) and the dates.
Errors:
- Order ID was not passed (code 9999)
options_get
Section titled “options_get”POST /api/admin/order/options_get
Returns a service’s configurable options for its Configurable options tab: every option of its product, hidden ones too, with the service’s choice.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: options (as product/admin/option_group_get lists them), choice (option id to value id, 0/1 or a quantity) and lines (the priced option lines the service was sold with).
Errors:
- Order ID was not passed (code 9999)
- Order not found (code 9999)
options_update
Section titled “options_update”POST /api/admin/order/options_update
Sets a service’s configurable options (any value, hidden ones too). No invoice is made.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
options |
object | Option id to value id, 0/1 (yes/no) or a quantity; an empty value leaves a hidden option unset. |
reprice |
boolean | Move the recurring price by the options’ difference at today’s rate. |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- The options are unchanged. (code 9999)
- The currency of this service is unknown, so its price cannot change with the options. (code 9999)
The change goes into the order’s status history. Change the hosting account on the server yourself when an option sets its resources.
move_targets
Section titled “move_targets”POST /api/admin/order/move_targets
Lists the products a service can be moved to: the other recurring products of the same type it is compatible with.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: An object of product id to name.
Errors:
- Order ID was not passed (code 9999)
- Order not found (code 9999)
move_product
Section titled “move_product”POST /api/admin/order/move_product
Moves a service to another product, as WHMCS’s product change on a service. No invoice is made.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
product_id |
integer, required | The new product, from admin/move_targets. |
recalculate |
boolean | Set the recurring price to the new product’s for the service’s cycle (with its options) at today’s rate. |
change_package |
boolean | For hosting: move the account to the new product’s plan on the panel first (a panel failure changes nothing). |
Returns: true.
Errors:
- Order ID was not passed (code 9999)
- Product ID was not passed (code 9999)
- The service can move only to another recurring product of the same type (hosting: on the same server, and reseller or not as now). (code 9999)
- The options of this service do not fit the new product. Change them first. (code 9999)
- The new product has no price for the billing cycle of this service, so the price cannot be recalculated. (code 9999)
The change goes into the order’s history.
move_client
Section titled “move_client”POST /api/admin/order/move_client
Moves a service, with its add-ons, to another client. Invoices, payments and credit stay with the old client; nothing changes on servers or registrars.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The main service’s order id. |
client_id |
integer, required | The new owner. |
Returns: true.
Errors:
- Order not found (code 9999)
- The service already belongs to this client. (code 9999)
- Client not found (code 9999)
- This is an add-on: move its main service, and its add-ons move with it. (code 9999)
- This service has an unpaid invoice …. Mark it paid or cancel it before you move the service. (code 9999)
- The service is billed in …, but the new client pays in …. (code 9999)
- This service is paid by a gateway subscription of its client. Cancel the subscription first, so the old client does not keep paying for the new owner. (code 9999)
- This service waits for review. Approve or refuse it first. (code 9999)
- This service has a waiting cancellation request. Accept or stop it first. (code 9999)
Both clients get a staff note and the orders a history line.
cancel_request_list
Section titled “cancel_request_list”POST /api/admin/order/cancel_request_list
Lists the waiting cancellation requests (Cancellation Requests), oldest first.
Permission: View orders (order.view)
No parameters.
Returns: A list; each has the request’s id, client_order_id, client_id, type (immediate or end_of_period), reason, status, created_at, updated_at, and order_title, order_status, expires_at, client_first_name, client_last_name.
cancel_request_get
Section titled “cancel_request_get”POST /api/admin/order/cancel_request_get
Returns an order’s waiting cancellation request.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: The request (id, client_order_id, client_id, type, reason, status, created_at, updated_at), or null.
Errors:
- Order ID was not passed (code 9999)
- Order Not Found (code 9999)
cancel_request_accept
Section titled “cancel_request_accept”POST /api/admin/order/cancel_request_accept
Accepts a waiting cancellation request: an Immediate one cancels the service now, an End of billing period one schedules it for the due date.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The request’s id. |
Returns: true.
Errors:
- Request ID was not passed (code 9999)
- This cancellation request is no longer waiting. (code 9999)
- The cancellation’s own errors.
cancel_request_stop
Section titled “cancel_request_stop”POST /api/admin/order/cancel_request_stop
Stops a waiting cancellation request; the service is not cancelled.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The request’s id. |
Returns: true.
Errors:
- Request ID was not passed (code 9999)
- This cancellation request is no longer waiting. (code 9999)
hold_list
Section titled “hold_list”POST /api/admin/order/hold_list
Lists the orders waiting for review (Waiting for review): held by the fraud check, a hosting network rule or an ID document check. Oldest first.
Permission: View orders (order.view)
No parameters.
Returns: A list; each has the hold’s id, client_order_id, client_id, invoice_id, reason (fraud, network or id_document), note, status, admin_id, created_at, updated_at, and order_title, client_first_name, client_last_name, client_email.
hold_get
Section titled “hold_get”POST /api/admin/order/hold_get
Returns the hold of an order waiting for review.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: id, reason, note and created_at, or null when the order is not held.
Errors:
- Order ID was not passed (code 9999)
hold_approve
Section titled “hold_approve”POST /api/admin/order/hold_approve
Approves a held order and the others of its checkout: the invoice is issued (paid from credit when it covers it) and setup carries on.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The hold’s id. |
Returns: true.
Errors:
- Hold ID was not passed (code 9999)
- This order is no longer waiting for review. (code 9999)
The client gets an email.
hold_refuse
Section titled “hold_refuse”POST /api/admin/order/hold_refuse
Refuses a held order and the others of its checkout: they and their invoice are cancelled.
Permission: Manage orders (order.manage); with ban, also Manage settings of Anti-Spam (antispam.manage_settings)
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The hold’s id. |
ban |
boolean | Also ban the client’s email address. |
Returns: true.
Errors:
- Hold ID was not passed (code 9999)
- This order is no longer waiting for review. (code 9999)
The client gets an email.
bulk_price_options
Section titled “bulk_price_options”POST /api/admin/order/bulk_price_options
Returns what the Bulk price update form offers.
Permission: View orders (order.view)
No parameters.
Returns: products (each id, title, is_addon, orders), periods (in use), statuses, default_statuses, currencies and default_currency.
bulk_price_preview
Section titled “bulk_price_preview”POST /api/admin/order/bulk_price_preview
Shows which services a bulk price update would change, with their old and new recurring prices.
Permission: View orders (order.view)
| Parameter | Type | Description |
|---|---|---|
product_ids |
array, required | The products (not domains). |
statuses |
array, required | Order statuses: active, suspended, pending_setup, failed_setup, failed_renew. |
currency |
string, required | Only orders in this currency. |
mode |
string, required | price (a fixed new price), increase (add an amount; negative lowers it) or product (the product’s current price for the order’s period). |
amount |
number | The new price or the amount to add; needed for price and increase. |
periods |
array | Only these billing periods, such as 1M. Empty: all. |
current_price |
number | Only orders at this price now. |
Returns: rows (each id, client_id, client, title, product_title, period, status, quantity, currency, expires_at, old_price, new_price, state (change, unchanged or skipped), skip, unpaid_invoice_id, subscription, recurring_discount), matched, change, unchanged, skipped, unpaid_invoices, subscriptions, clients and fingerprint.
Errors:
- Choose at least one product. (code 9999)
- Unknown product, or a product whose renewals do not use the order price (domains). (code 9999)
- Unknown billing period. (code 9999)
- Choose at least one order status. (code 9999)
- Unknown currency. (code 9999)
- Choose how to set the new price. (code 9999)
- Enter an amount to add other than 0 (a negative amount lowers the price). (code 9999)
bulk_price_apply
Section titled “bulk_price_apply”POST /api/admin/order/bulk_price_apply
Applies a previewed bulk price update. Applying prices again and refuses when anything changed since the preview.
Permission: Manage orders (order.manage)
| Parameter | Type | Description |
|---|---|---|
fingerprint |
string, required | The preview’s fingerprint. |
product_ids |
array, required | The same filters as the preview: product_ids, statuses, currency, mode, amount, periods, current_price. |
email |
boolean | Email each client their old and new prices (one email per client). |
Returns: updated, emailed, unpaid_invoices and subscriptions (left at the old amount).
Errors:
- Preview the update first (code 9999)
- The matching services changed since the preview. Preview again before applying. (code 9999)
- No service gets a new price. (code 9999)
- Order #… changed while applying. Nothing was changed; preview again. (code 9999)
The new price starts with the next invoice; unpaid invoices and fixed-amount gateway subscriptions keep the old amount. Each changed order gets a history line.
Client calls
Section titled “Client calls”get_list (client)
Section titled “get_list (client)”POST /api/client/order/get_list
Lists the client’s own orders (services), newest first.
| Parameter | Type | Description |
|---|---|---|
status |
string | Only this status. |
type |
string | Only this service type, such as hosting or domain. |
product_id |
integer | Only this product. |
title |
string | Text to find in the title. |
search |
string | An order id or text in the title. |
period |
string | Only this billing period. |
show_action_required |
boolean | Only orders pending setup or failed. |
hide_addons |
boolean | Leave out add-ons. |
active_first |
boolean | Active services first. |
expiring |
boolean | When given, only active services due for a renewal invoice soon (filters other than id are ignored). |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list of orders with the fields of client/get.
An authorized user needs View services (products).
get (client)
Section titled “get (client)”POST /api/client/order/get
Returns one of the client’s orders.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: The order with the fields of admin/get, without staff notes, staff-only meta, auto_suspend_off and any password in config.
Errors:
- Order id required (code 9999)
- Order not found (code 404)
An authorized user needs View services (products).
addons (client)
Section titled “addons (client)”POST /api/client/order/addons
Lists the add-ons of one of the client’s services.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The main order’s id. |
Returns: A list of orders with the fields of client/get.
Errors:
- Order id required (code 9999)
- Order not found (code 404)
An authorized user needs View services (products).
service (client)
Section titled “service (client)”POST /api/client/order/service
Returns the service record behind one of the client’s active orders.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: The service as its module formats it for the client, or null when there is none.
Errors:
- Order id required (code 9999)
- Order not found (code 404)
- Order is not active (code 9999)
An authorized user needs View services (products).
upgradables (client)
Section titled “upgradables (client)”POST /api/client/order/upgradables
Lists the products a service’s product lists as upgrades, in the client’s language.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: An object of product id to name.
Errors:
- Order id required (code 9999)
- Order not found (code 404)
An authorized user needs View services (products).
upgrade_options (client)
Section titled “upgrade_options (client)”POST /api/client/order/upgrade_options
Lists what one of the client’s services can change to now (upgrades, downgrades, other billing cycles), each with its prorated price.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: available, reason (why not, for the client), notice, current (product_id, title, period, price, expires_at, currency, option_lines), options (each product_id, title, period, price, same_product, options, option_lines and the quote: kind (upgrade or downgrade), same_cycle, days_total, days_left, credit, charge, amount, period_start, expires_at, new_expires_at), waiting (a change waiting for payment, or null), options_change and product_options (configurable options the client may change alone).
Errors:
- Order id required (code 9999)
- Order not found (code 404)
An authorized user needs View services (products).
upgrade (client)
Section titled “upgrade (client)”POST /api/client/order/upgrade
Changes one of the client’s services to another product or billing cycle (or, with options, its configurable options). A positive amount makes an invoice and the change applies once it is paid; otherwise it applies at once and a negative amount goes to the client’s credit.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
product_id |
integer, required | The new product (the same one for a billing cycle change). |
period |
string, required | The new billing cycle, such as 1Y. |
options |
object | New configurable options (option id to value), to change them alone; then send the current product and cycle. |
Returns: id (the change), status (pending while its invoice waits, else the result), amount and invoice_hash (to open the invoice, or null).
Errors:
- Choose the new product (code 9999)
- Choose the billing cycle (code 9999)
- Order not found (code 404)
- This change is not available for this service. (code 9999)
- This service is being changed. Please try again in a moment. (code 9999)
- Change the options and the product or billing cycle one at a time. (code 9999)
- The reason from
client/upgrade_options, such as “Pay the open invoice of this service first.”
An authorized user needs Place new orders (orders).
Example
Request parameters:
{ "id": 31, "product_id": 5, "period": "1M"}result:
{ "id": 4, "status": "pending", "amount": 3.5, "invoice_hash": "a1b2c3d4e5f6"}upgrade_options_quote (client)
Section titled “upgrade_options_quote (client)”POST /api/client/order/upgrade_options_quote
Prices a change of a service’s configurable options alone (same product and cycle).
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
options |
object | The new choice: option id to value id, 0/1 or a quantity. |
Returns: An entry as in options of client/upgrade_options, with options_change true.
Errors:
- Order not found (code 404)
- Upgrades and downgrades are not available. (code 9999)
- Choose other options than the ones this service has. (code 9999)
- The options of this service cannot be changed here. Please contact us. (code 9999)
- This change is not available for this service. (code 9999)
An authorized user needs View services (products).
addon_offers (client)
Section titled “addon_offers (client)”POST /api/client/order/addon_offers
Lists the add-ons one of the client’s active services can take now, priced to its due date.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The service’s order id. |
Returns: A list with the fields of admin/addon_offers.
Errors:
- Order not found (code 404)
A store call: when the store is closed to the client it returns an empty list. An authorized user needs View services (products).
addon_order (client)
Section titled “addon_order (client)”POST /api/client/order/addon_order
Puts an add-on for one of the client’s services in the cart; the client then checks out.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The service’s order id. |
product_id |
integer, required | An add-on from client/addon_offers. |
Returns: true when it was added to the cart.
Errors:
- Choose the add-on (code 9999)
- Order not found (code 404)
- This add-on cannot be ordered for this service. (code 9999)
- The store is not available. (code 9999)
A store call. An authorized user needs Place new orders (orders).
delete (client)
Section titled “delete (client)”POST /api/client/order/delete
Deletes one of the client’s orders that is pending or failed setup and was never paid, with a free domain bundled with it.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: true.
Errors:
- Order id required (code 9999)
- Order not found (code 404)
- Only pending and failed setup orders can be deleted. (code 9999)
- A paid order cannot be deleted. Please contact support. (code 9999)
Its unpaid invoice is cancelled. An authorized user needs Place new orders (orders).
cancel_request (client)
Section titled “cancel_request (client)”POST /api/client/order/cancel_request
Asks staff to cancel one of the client’s active services, now or at the end of its billing period.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
type |
string, required | immediate or end_of_period. |
reason |
string, required | Why, up to 2000 characters. |
Returns: true.
Errors:
- Choose when the service ends (code 9999)
- Please tell us why you want to cancel. (code 9999)
- Invalid cancellation type. (code 9999)
- Only an active service can be cancelled. (code 9999)
- This service cannot be cancelled at the end of its period. Choose Immediate, or open a ticket. (code 9999)
- We have already received this request. (code 9999)
Staff get an email and a bell notice. While it waits, no renewal invoice is made. With the Orders setting on, the daily cron accepts waiting requests. An authorized user needs Place new orders (orders).
cancel_request_get (client)
Section titled “cancel_request_get (client)”POST /api/client/order/cancel_request_get
Returns the waiting cancellation request of one of the client’s services.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: type, reason and created_at, or null.
Errors:
- Order not found (code 404)
An authorized user needs View services (products).
cancel_request_withdraw (client)
Section titled “cancel_request_withdraw (client)”POST /api/client/order/cancel_request_withdraw
Takes back the waiting cancellation request of one of the client’s services.
| Parameter | Type | Description |
|---|---|---|
id |
integer, required | The order’s id. |
Returns: true.
Errors:
- Order not found (code 404)
- This service has no cancellation request waiting. (code 9999)
An authorized user needs Place new orders (orders).

