{ "openapi": "3.1.0", "info": { "title": "Ex2 account API", "version": "1", "description": "The signed-in customer's own Ex2 account: services, domain names, invoices, support tickets, and what each connection did. With the customer's permission, also order domain names and plans, renew, change plans and cancel; and change domain names' nameservers and lock and transfer them away: each kind of change needs its scope, which only the customer's tick on the consent page grants. Sign-in is OAuth 2.1 with PKCE (S256), as for Ex2's account MCP server; ask for the resource https://api.ex2.com/api/v1/account. Applications register themselves with a Client ID Metadata Document or at https://api.ex2.com/oauth/register (RFC 7591). Errors are RFC 9457 problem details with a code; lists are paginated with next_cursor. Fields are added, never renamed or removed. A breaking change comes as a new version (/api/v2); the old one then keeps answering for at least 12 months, with Deprecation and Sunset headers (RFC 9745, RFC 8594) and a notice on the developers page. Limits: 120 requests a minute per connection; per account and hour, 20 orders, renewals, plan changes, cancellations and transfers away; a 429 says when to try again (Retry-After)." }, "externalDocs": { "url": "https://www.ex2.com/en/developers", "description": "Ex2 for developers" }, "servers": [ { "url": "https://api.ex2.com/api/v1" } ], "security": [ { "ex2_oauth": [ "account:read" ] }, { "ex2_token": [] } ], "paths": { "/account": { "get": { "operationId": "getAccount", "summary": "The account", "description": "The client account the connection was made for: name, company, email, country, currency, credit balance.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "client_area_url" ], "properties": { "account": { "$ref": "#/components/schemas/Account" }, "client_area_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/account/services": { "get": { "operationId": "listServices", "summary": "Services", "description": "Hosting plans and other services: plan, domain, status, billing cycle, next due date, recurring price, manage link.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "all" ], "default": "active" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only those of this domain name or under it (www., capitals and a final dot do not matter)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "currency", "services", "next_cursor" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass it as cursor for the next page; null on the last page." } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/account/domains": { "get": { "operationId": "listDomains", "summary": "Domain names", "description": "Domain names: status, dates, renewal price, auto-renewal, manage link.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "all" ], "default": "active" } }, { "name": "domain", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only those of this domain name or under it (www., capitals and a final dot do not matter)." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "currency", "domains", "next_cursor" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "domains": { "type": "array", "items": { "$ref": "#/components/schemas/Domain" } }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass it as cursor for the next page; null on the last page." } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/account/invoices": { "get": { "operationId": "listInvoices", "summary": "Invoices", "description": "Invoices, most recent first: amounts with taxes, status, whether overdue, the link to view and pay. A page can hold fewer than limit items (drafts are never shown): follow next_cursor.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "unpaid", "paid", "all" ], "default": "unpaid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "invoices", "next_cursor" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "invoices": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass it as cursor for the next page; null on the last page." } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/account/tickets": { "get": { "operationId": "listTickets", "summary": "Support tickets", "description": "Support tickets: subject, department, status, dates. Never the messages.", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "open", "all" ], "default": "open" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "tickets", "tickets_url", "next_cursor" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "tickets": { "type": "array", "items": { "$ref": "#/components/schemas/Ticket" } }, "tickets_url": { "type": "string", "format": "uri" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass it as cursor for the next page; null on the last page." } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/account/audit": { "get": { "operationId": "listAudit", "summary": "Audit log", "description": "What this application did for this login on this account, through this API or the account MCP server, newest first: when, which operation, how it ended (never another application's entries). Kept 180 days.", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The next_cursor of the previous page." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "entries", "retention_days", "next_cursor" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEntry" } }, "retention_days": { "type": "integer" }, "next_cursor": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass it as cursor for the next page; null on the last page." } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/account/openapi.json": { "get": { "operationId": "getOpenApi", "summary": "This document", "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/account/orders/domain": { "get": { "operationId": "quoteDomainOrder", "summary": "Quote a domain name order", "description": "Whether the name can be registered (or transferred in), its price in the account's currency, the registry's rule on the registrant's address and its extra fields, and the terms of service to accept. Changes nothing.", "parameters": [ { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 253 }, "description": "The domain name, like example.com." }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "register", "transfer" ], "default": "register" }, "description": "register a free name, or transfer one registered elsewhere to Ex2." }, { "name": "years", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1 }, "description": "How many years, 1 by default." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "type", "years", "available", "price", "registrant", "fields", "terms", "note" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "string" }, "type": { "type": "string" }, "years": { "type": "integer" }, "available": { "type": "boolean" }, "price": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "description": "In the account's currency." }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "registrant": { "type": "object", "required": [ "country", "eligible", "rule" ], "properties": { "country": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "eligible": { "type": "boolean" }, "rule": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/DomainField" } }, "terms": { "$ref": "#/components/schemas/Terms" }, "note": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-ex2-action": "quote_domain_order" }, "post": { "operationId": "orderDomain", "summary": "Order a domain name", "description": "Orders the registration, or the transfer in (with auth_code), for the account: an order and its invoice, to pay (action_required). accept_terms is the quote's terms.version, once the customer accepted the terms; fields are the registry's extra fields. Needs an Idempotency-Key.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "A new value for each action (a UUID). The same key with the same request gets the first answer again (with Idempotent-Replayed: true) instead of acting twice, for 24 hours." } ], "responses": { "201": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "type", "years", "order_id", "invoice", "action_required", "terms_version", "next" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "string" }, "type": { "type": "string" }, "years": { "type": "integer" }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "invoice": { "oneOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "null" } ] }, "action_required": { "oneOf": [ { "$ref": "#/components/schemas/ActionRequired" }, { "type": "null" } ] }, "terms_version": { "type": "string" }, "next": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "idempotency_key_reused: the key came with another request in the last 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The domain name, like example.com." }, "type": { "type": "string", "enum": [ "register", "transfer" ], "default": "register", "description": "register a free name, or transfer one registered elsewhere to Ex2." }, "years": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "How many years, 1 by default." }, "auth_code": { "type": "string", "minLength": 1, "maxLength": 255, "description": "For a transfer: the transfer (EPP) code the current registrar gave." }, "fields": { "type": "object", "description": "The registry's extra fields for the extension, by name, as quote_domain_order lists them (fields): text, one of the options, or true/false." }, "accept_terms": { "type": "string", "maxLength": 64, "description": "The version of Ex2's terms of service the customer accepted for this order: terms.version of the quote, sent only once the customer has accepted them." } }, "required": [ "domain", "accept_terms" ], "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:billing" ] }, { "ex2_token": [] } ], "x-ex2-action": "order_domain" } }, "/account/orders/plan": { "get": { "operationId": "quotePlanOrder", "summary": "Quote a plan order", "description": "The price of a plan of the catalogue for a site's domain name: first payment (with the first-year discount, if any) and renewal, and the terms of service to accept. Changes nothing.", "parameters": [ { "name": "plan", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "description": "The plan's id in Ex2's catalogue (list_plans, GET /api/v1/plans), like green-power." }, { "name": "billing_cycle", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "monthly", "quarterly", "semiannually", "annually", "biennially", "triennially" ], "default": "annually" }, "description": "How the plan is billed; annually by default." }, { "name": "domain", "in": "query", "required": true, "schema": { "type": "string", "minLength": 3, "maxLength": 253 }, "description": "The domain name, like example.com." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "plan", "domain", "currency", "price", "terms", "note" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "plan": { "type": "object", "required": [ "id", "product", "billing_cycle" ], "properties": { "id": { "type": "string", "description": "The plan's id in the catalogue API." }, "product": { "type": "string" }, "billing_cycle": { "type": "string" } }, "additionalProperties": false }, "domain": { "type": "string" }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "type": "object", "required": [ "first_payment", "setup_fee", "recurring", "first_year_discount" ], "properties": { "first_payment": { "type": "number", "description": "In the account's currency." }, "setup_fee": { "type": "number", "description": "In the account's currency." }, "recurring": { "type": "number", "description": "In the account's currency." }, "first_year_discount": { "oneOf": [ { "type": "number", "description": "Percent off the first year." }, { "type": "null" } ] } }, "additionalProperties": false }, "terms": { "$ref": "#/components/schemas/Terms" }, "note": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-ex2-action": "quote_plan_order" }, "post": { "operationId": "orderPlan", "summary": "Order a plan", "description": "Orders the plan for the account and the site's domain name: an order and its invoice, to pay (action_required); Ex2 sets the service up once it is paid. Needs an Idempotency-Key.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "A new value for each action (a UUID). The same key with the same request gets the first answer again (with Idempotent-Replayed: true) instead of acting twice, for 24 hours." } ], "responses": { "201": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "plan", "domain", "order_id", "invoice", "action_required", "terms_version", "next" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "plan": { "type": "object", "required": [ "id", "product", "billing_cycle" ], "properties": { "id": { "type": "string", "description": "The plan's id in the catalogue API." }, "product": { "type": "string" }, "billing_cycle": { "type": "string" } }, "additionalProperties": false }, "domain": { "type": "string" }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "invoice": { "oneOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "null" } ] }, "action_required": { "oneOf": [ { "$ref": "#/components/schemas/ActionRequired" }, { "type": "null" } ] }, "terms_version": { "type": "string" }, "next": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "idempotency_key_reused: the key came with another request in the last 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$", "description": "The plan's id in Ex2's catalogue (list_plans, GET /api/v1/plans), like green-power." }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "semiannually", "annually", "biennially", "triennially" ], "default": "annually", "description": "How the plan is billed; annually by default." }, "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "The domain name, like example.com." }, "accept_terms": { "type": "string", "maxLength": 64, "description": "The version of Ex2's terms of service the customer accepted for this order: terms.version of the quote, sent only once the customer has accepted them." } }, "required": [ "plan", "domain", "accept_terms" ], "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:billing" ] }, { "ex2_token": [] } ], "x-ex2-action": "order_plan" } }, "/account/domains/{id}/registrar": { "get": { "operationId": "getDomainRegistrarSettings", "summary": "Nameservers and lock", "description": "The domain name at its registrar: its nameservers and whether it is locked against transfers.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The domain's id (GET /api/v1/account/domains)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "nameservers", "locked" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "object", "required": [ "id", "domain" ], "properties": { "id": { "type": "integer" }, "domain": { "type": "string" } }, "additionalProperties": false }, "nameservers": { "type": "array", "items": { "type": "string" } }, "locked": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-ex2-action": "get_domain_registrar_settings" } }, "/account/domains/{id}/nameservers": { "post": { "operationId": "setDomainNameservers", "summary": "Change the nameservers", "description": "Points the domain name to 2 to 5 other nameservers, then reads them back.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The domain's id (GET /api/v1/account/domains)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "nameservers", "locked", "note" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "object", "required": [ "id", "domain" ], "properties": { "id": { "type": "integer" }, "domain": { "type": "string" } }, "additionalProperties": false }, "nameservers": { "type": "array", "items": { "type": "string" } }, "locked": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] }, "note": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "nameservers": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$", "maxLength": 253 }, "minItems": 2, "maxItems": 5, "uniqueItems": true, "description": "2 to 5 nameserver host names, like ns1.example.net." } }, "required": [ "nameservers" ], "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:domains" ] }, { "ex2_token": [] } ], "x-ex2-action": "set_domain_nameservers" } }, "/account/domains/{id}/lock": { "post": { "operationId": "setDomainLock", "summary": "Lock or unlock", "description": "Locks the domain name against transfers away, or unlocks it, then reads it back.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The domain's id (GET /api/v1/account/domains)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "nameservers", "locked" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "object", "required": [ "id", "domain" ], "properties": { "id": { "type": "integer" }, "domain": { "type": "string" } }, "additionalProperties": false }, "nameservers": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "locked": { "oneOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "locked": { "type": "boolean", "description": "true: the registrar refuses transfers away; false: unlocked, as a transfer away needs." } }, "required": [ "locked" ], "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:domains" ] }, { "ex2_token": [] } ], "x-ex2-action": "set_domain_lock" } }, "/account/domains/{id}/transfer_out": { "get": { "operationId": "previewDomainTransferOut", "summary": "What a transfer away would do", "description": "Changes nothing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The domain's id (GET /api/v1/account/domains)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "transfer_out" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "object", "required": [ "id", "domain" ], "properties": { "id": { "type": "integer" }, "domain": { "type": "string" } }, "additionalProperties": false }, "transfer_out": { "type": "object", "required": [ "consequences" ], "properties": { "consequences": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-ex2-action": "preview_domain_transfer_out" }, "post": { "operationId": "transferDomainOut", "summary": "Transfer away", "description": "Unlocks the domain name and has its transfer code sent by email to the customer (by Ex2 to the account's address, or by the registrar to the registrant's): the code is never in an answer. Needs an Idempotency-Key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The domain's id (GET /api/v1/account/domains)." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "A new value for each action (a UUID). The same key with the same request gets the first answer again (with Idempotent-Replayed: true) instead of acting twice, for 24 hours." } ], "responses": { "201": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "unlocked", "transfer_code", "next" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "object", "required": [ "id", "domain" ], "properties": { "id": { "type": "integer" }, "domain": { "type": "string" } }, "additionalProperties": false }, "unlocked": { "type": "boolean" }, "transfer_code": { "type": "object", "required": [ "sent_by", "sent_to" ], "properties": { "sent_by": { "type": "string", "enum": [ "ex2", "registrar" ] }, "sent_to": { "type": "string", "enum": [ "account_email", "registrant_email" ] } }, "additionalProperties": false }, "next": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "idempotency_key_reused: the key came with another request in the last 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:domains" ] }, { "ex2_token": [] } ], "x-ex2-action": "transfer_domain_out" } }, "/account/domains/{id}/auto_renew": { "post": { "operationId": "setDomainAutoRenew", "summary": "Turn automatic renewal on or off", "description": "Off: Ex2 sends no renewal invoice and the domain name expires on its expiry date. Answers the domain as it is now.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The domain's id (GET /api/v1/account/domains)." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "$ref": "#/components/schemas/Domain" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "true: Ex2 invoices the renewal before the expiry date; false: no renewal invoice, the domain expires on its date." } }, "required": [ "enabled" ], "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:billing" ] }, { "ex2_token": [] } ], "x-ex2-action": "set_domain_auto_renew" } }, "/account/domains/{id}/renew": { "post": { "operationId": "renewDomain", "summary": "Renew a domain name", "description": "An order and its invoice for 1 to 10 more years. Nothing is renewed until the invoice is paid: action_required says what the customer does. Needs an Idempotency-Key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The domain's id (GET /api/v1/account/domains)." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "A new value for each action (a UUID). The same key with the same request gets the first answer again (with Idempotent-Replayed: true) instead of acting twice, for 24 hours." } ], "responses": { "201": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "domain", "years", "order_id", "invoice", "action_required" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "domain": { "type": "object", "required": [ "id", "domain" ], "properties": { "id": { "type": "integer" }, "domain": { "type": "string" } }, "additionalProperties": false }, "years": { "type": "integer" }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "invoice": { "oneOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "null" } ] }, "action_required": { "oneOf": [ { "$ref": "#/components/schemas/ActionRequired" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "idempotency_key_reused: the key came with another request in the last 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "years": { "type": "integer", "minimum": 1, "maximum": 10, "default": 1, "description": "How many years to add, 1 by default." } }, "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:billing" ] }, { "ex2_token": [] } ], "x-ex2-action": "renew_domain" } }, "/account/services/{id}/plan_change": { "get": { "operationId": "quotePlanChange", "summary": "Quote a plan change", "description": "What moving the service to another plan of the catalogue would cost: the amount due now, prorated to the next due date, and the new recurring price. Changes nothing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The service's id (GET /api/v1/account/services)." }, { "name": "plan", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$" }, "description": "The new plan's id in Ex2's catalogue (list_plans, GET /api/v1/plans), like green-xtreme." }, { "name": "billing_cycle", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "monthly", "quarterly", "semiannually", "annually", "biennially", "triennially" ] }, "description": "The billing cycle after the change; the current one by default." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "service", "new_plan", "currency", "amount_due_now", "note" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "service": { "$ref": "#/components/schemas/Service" }, "new_plan": { "$ref": "#/components/schemas/NewPlan" }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "amount_due_now": { "oneOf": [ { "type": "number", "description": "In the account's currency." }, { "type": "null" } ] }, "note": { "type": "string" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-ex2-action": "quote_plan_change" }, "post": { "operationId": "changePlan", "summary": "Change plan", "description": "Orders the change (upgrade or downgrade). An amount due makes an invoice to pay (action_required); the change follows payment. Needs an Idempotency-Key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The service's id (GET /api/v1/account/services)." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "A new value for each action (a UUID). The same key with the same request gets the first answer again (with Idempotent-Replayed: true) instead of acting twice, for 24 hours." } ], "responses": { "201": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "service", "new_plan", "order_id", "invoice", "action_required" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "service": { "type": "object", "required": [ "id", "product" ], "properties": { "id": { "type": "integer" }, "product": { "type": "string" } }, "additionalProperties": false }, "new_plan": { "$ref": "#/components/schemas/NewPlan" }, "order_id": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "invoice": { "oneOf": [ { "$ref": "#/components/schemas/Invoice" }, { "type": "null" } ] }, "action_required": { "oneOf": [ { "$ref": "#/components/schemas/ActionRequired" }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "idempotency_key_reused: the key came with another request in the last 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "string", "pattern": "^[a-z0-9-]{1,60}$", "description": "The new plan's id in Ex2's catalogue (list_plans, GET /api/v1/plans), like green-xtreme." }, "billing_cycle": { "type": "string", "enum": [ "monthly", "quarterly", "semiannually", "annually", "biennially", "triennially" ], "description": "The billing cycle after the change; the current one by default." } }, "required": [ "plan" ], "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:billing" ] }, { "ex2_token": [] } ], "x-ex2-action": "change_plan" } }, "/account/services/{id}/cancellation": { "get": { "operationId": "previewCancellation", "summary": "What a cancellation would do", "description": "The date the service would end and what happens then. Changes nothing.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The service's id (GET /api/v1/account/services)." }, { "name": "when", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "end_of_billing_period", "immediate" ], "default": "end_of_billing_period" }, "description": "end_of_billing_period (default): the service runs until its next due date, then ends. immediate: it ends at Ex2's next daily run." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "service", "cancellation", "terms_url" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "service": { "$ref": "#/components/schemas/Service" }, "cancellation": { "type": "object", "required": [ "when", "effective_date", "consequences" ], "properties": { "when": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "consequences": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "terms_url": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-ex2-action": "preview_cancellation" }, "post": { "operationId": "cancelService", "summary": "Cancel a service", "description": "Sends the cancellation (at the end of the billing period by default). Files, databases and mailboxes are deleted when the service ends. Needs an Idempotency-Key.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 }, "description": "The service's id (GET /api/v1/account/services)." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": "A new value for each action (a UUID). The same key with the same request gets the first answer again (with Idempotent-Replayed: true) instead of acting twice, for 24 hours." } ], "responses": { "201": { "description": "Done", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "service", "cancellation" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "service": { "type": "object", "required": [ "id", "product", "domain" ], "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "domain": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "cancellation": { "type": "object", "required": [ "when", "effective_date", "requested" ], "properties": { "when": { "type": "string" }, "effective_date": { "type": "string", "format": "date" }, "requested": { "type": "boolean" } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "400": { "description": "invalid_parameter: a parameter is not one the endpoint accepts. Also invalid_body, and idempotency_key_required.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "not_found: no domain name or service with this id on the account.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Not possible now: refused (Ex2's billing system or the registrar said no, with its reason), not_allowed, not_renewable, not_changeable, not_cancellable, already_requested, payment_method_missing (with action_required), not_offered, not_available, registrant_ineligible (with action_required), terms_not_accepted (with terms), not_bridged (the service's server is not connected to the API yet), zone_changed (read the zone again), idempotency_in_progress.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "idempotency_key_reused: the key came with another request in the last 24 hours.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "outcome_unknown: Ex2's billing system did not answer, so whether it was done is unknown (check before retrying with a new key); not_applied: accepted but not applied; not_delivered: the transfer code email could not be sent (with action_required).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "when": { "type": "string", "enum": [ "end_of_billing_period", "immediate" ], "default": "end_of_billing_period", "description": "end_of_billing_period (default): the service runs until its next due date, then ends. immediate: it ends at Ex2's next daily run." }, "reason": { "type": "string", "maxLength": 500, "description": "Why, in the customer's words (optional); Ex2's team reads it." } }, "additionalProperties": false } } } }, "security": [ { "ex2_oauth": [ "account:read", "account:billing" ] }, { "ex2_token": [] } ], "x-ex2-action": "cancel_service" } }, "/account/payment_methods": { "get": { "operationId": "getPaymentMethodsLink", "summary": "Where to manage payment methods", "description": "The client area page where the customer adds or changes a payment method: card details never go through the API.", "parameters": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "account", "action_required" ], "properties": { "account": { "$ref": "#/components/schemas/AccountRef" }, "action_required": { "$ref": "#/components/schemas/ActionRequired" } }, "additionalProperties": false } } } }, "401": { "description": "unauthorized: no access token, or one that is invalid, expired, revoked or for another resource. WWW-Authenticate gives the resource metadata URL.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "insufficient_scope, permission_denied (the login lacks the WHMCS permission for this data), access_lost (the login no longer manages the account: the connection is closed), or outside_limit (the customer limited the connection to one service or domain name; invoices, tickets and orders are then out of its reach).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "rate_limited: 120 requests a minute per connection; Retry-After says when to try again.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "whmcs_unavailable: Ex2's billing system did not answer; Retry-After says when to try again. The connection is kept. server_unavailable: the service's server did not answer.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "x-ex2-action": "get_payment_methods_link" } } }, "components": { "securitySchemes": { "ex2_token": { "type": "http", "scheme": "bearer", "description": "An API token (ex2pat_…) the customer made on https://api.ex2.com/oauth/connections: one account, reading plus the actions ticked when it was made, 30, 90, 365 days; also valid at the account MCP server." }, "ex2_oauth": { "type": "oauth2", "description": "Authorization code with PKCE (S256 only); resource=https://api.ex2.com/api/v1/account. Metadata: https://api.ex2.com/.well-known/oauth-authorization-server and https://api.ex2.com/.well-known/oauth-protected-resource/api/v1/account.", "flows": { "authorizationCode": { "authorizationUrl": "https://api.ex2.com/oauth/authorize", "tokenUrl": "https://api.ex2.com/oauth/token", "refreshUrl": "https://api.ex2.com/oauth/token", "scopes": { "account:read": "Read the account: services, domains, invoices, tickets.", "account:billing": "Billing actions: orders of domain names and plans, renewals and automatic renewal, plan changes, cancellations. The customer allows them on the consent page; purchases make invoices the customer pays.", "account:domains": "Domain actions: nameservers, registrar lock, transfer away (the code goes to the customer by email). The customer allows them on the consent page." } } } } }, "schemas": { "Account": { "type": "object", "required": [ "id", "name", "company", "email", "country", "currency", "credit_balance", "status" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "type": "string" }, "country": { "oneOf": [ { "type": "string", "description": "ISO 3166-1 alpha-2." }, { "type": "null" } ] }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "credit_balance": { "type": "number", "description": "In the account's currency." }, "status": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "AccountRef": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" } }, "additionalProperties": false }, "Service": { "type": "object", "required": [ "id", "product", "group", "domain", "status", "billing_cycle", "recurring_amount", "next_due_date", "registration_date", "manage_url" ], "properties": { "id": { "type": "integer" }, "product": { "type": "string" }, "group": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Active, Pending, Suspended, Cancelled, Terminated…" }, "billing_cycle": { "type": "string" }, "recurring_amount": { "type": "number", "description": "In the account's currency." }, "next_due_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "registration_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "manage_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "Domain": { "type": "object", "required": [ "id", "domain", "status", "registration_date", "expiry_date", "next_due_date", "renewal_price", "auto_renew", "manage_url" ], "properties": { "id": { "type": "integer" }, "domain": { "type": "string" }, "status": { "type": "string" }, "registration_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "expiry_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "next_due_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "renewal_price": { "type": "number", "description": "In the account's currency." }, "auto_renew": { "type": "boolean" }, "manage_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "Invoice": { "type": "object", "required": [ "id", "number", "date", "due_date", "subtotal", "tax", "credit", "total", "currency", "status", "overdue", "view_url" ], "properties": { "id": { "type": "integer" }, "number": { "type": "string" }, "date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "due_date": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "subtotal": { "type": "number", "description": "In the account's currency." }, "tax": { "type": "number", "description": "In the account's currency." }, "credit": { "type": "number", "description": "In the account's currency." }, "total": { "type": "number", "description": "In the account's currency." }, "currency": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "description": "Unpaid, Paid, Cancelled, Refunded, Collections, Payment Pending." }, "overdue": { "type": "boolean" }, "view_url": { "type": "string", "format": "uri" } }, "additionalProperties": false }, "Ticket": { "type": "object", "required": [ "number", "subject", "department", "status", "opened", "last_reply" ], "properties": { "number": { "type": "string" }, "subject": { "type": "string" }, "department": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "opened": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "last_reply": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "additionalProperties": false }, "AuditEntry": { "type": "object", "required": [ "at", "application", "channel", "action", "status" ], "properties": { "at": { "type": "string", "format": "date-time" }, "application": { "type": "string" }, "channel": { "type": "string", "enum": [ "api", "mcp" ] }, "action": { "type": "string", "description": "GET /api/v1/account/…, or tool for the account MCP server." }, "status": { "type": "integer", "description": "The HTTP status; 200 or 400 for an MCP tool." } }, "additionalProperties": false }, "Problem": { "type": "object", "description": "RFC 9457 problem details.", "required": [ "type", "title", "status", "detail", "code" ], "additionalProperties": false, "properties": { "type": { "type": "string", "description": "urn:ex2:problem:" }, "title": { "type": "string" }, "status": { "type": "integer" }, "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "not_found", "method_not_allowed", "unauthorized", "insufficient_scope", "invalid_parameter", "permission_denied", "access_lost", "outside_limit", "rate_limited", "whmcs_unavailable", "unavailable", "invalid_body", "idempotency_key_required", "idempotency_key_reused", "idempotency_in_progress", "refused", "not_allowed", "not_renewable", "not_changeable", "not_cancellable", "already_requested", "payment_method_missing", "outcome_unknown", "not_applied", "not_offered", "not_available", "registrant_ineligible", "terms_not_accepted", "not_delivered", "not_bridged", "zone_changed", "server_unavailable", "protected_record", "busy" ] }, "action_required": { "$ref": "#/components/schemas/ActionRequired", "description": "What the customer does to get past this." }, "terms": { "$ref": "#/components/schemas/Terms", "description": "With terms_not_accepted: the terms to accept." } } }, "DnsRecord": { "type": "object", "required": [ "line", "name", "type", "ttl", "data", "editable" ], "properties": { "line": { "type": "integer", "description": "Its line in the zone: what an edit or a removal names." }, "name": { "type": "string", "description": "The full name, without the final dot." }, "type": { "type": "string" }, "ttl": { "type": "integer" }, "data": { "type": "array", "items": { "type": "string" }, "description": "As the zone has it: MX priority and host, TXT in pieces of 255 bytes..." }, "editable": { "type": "boolean", "description": "Whether an action may change it (A, AAAA, CNAME, MX, TXT, SRV, CAA)." } }, "additionalProperties": false }, "Certificate": { "type": "object", "required": [ "host", "domains", "issuer", "expires", "days_left", "self_signed" ], "properties": { "host": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } }, "issuer": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "expires": { "oneOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "days_left": { "oneOf": [ { "type": "integer" }, { "type": "null" } ] }, "self_signed": { "type": "boolean" } }, "additionalProperties": false }, "UsageItem": { "type": "object", "required": [ "id", "label", "used", "limit", "unit" ], "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "used": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "limit": { "oneOf": [ { "type": "number", "description": "null: unlimited." }, { "type": "null" } ] }, "unit": { "type": "string", "enum": [ "bytes", "count" ] } }, "additionalProperties": false }, "WordPressSite": { "type": "object", "required": [ "site", "domains", "url", "name", "version", "error" ], "properties": { "site": { "type": "string", "description": "The domain the site is known by here." }, "domains": { "type": "array", "items": { "type": "string" } }, "url": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "version": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why WordPress did not answer; null when it did." } }, "additionalProperties": false }, "SshKey": { "type": "object", "required": [ "name", "type", "fingerprint", "comment", "authorized" ], "additionalProperties": false, "properties": { "name": { "type": "string" }, "type": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "ssh-ed25519, ecdsa-sha2-…, ssh-rsa…; null when cPanel did not give the key." }, "fingerprint": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "SHA256:… as ssh-keygen -lf shows it." }, "comment": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "authorized": { "type": "boolean", "description": "Whether it may log in." }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } } }, "WordPressCopy": { "type": "object", "required": [ "name", "size_bytes", "created_at" ], "properties": { "name": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "description": "A copy of a site's database, in the account's ex2-backups folder (outside the site); the customer deletes old ones." }, "SiteExport": { "type": "object", "required": [ "name", "size_bytes", "created_at", "site", "expires_at", "download_url" ], "properties": { "name": { "type": "string" }, "size_bytes": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "site": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The domain of its site; null when that site is no longer on the service." }, "expires_at": { "type": "string", "format": "date-time", "description": "When it is deleted." }, "download_url": { "type": "string", "format": "uri", "description": "GET it with an access token that may make archives (account:export)." } }, "additionalProperties": false }, "WordPressItem": { "type": "object", "required": [ "name", "title", "status", "version", "update" ], "properties": { "name": { "type": "string" }, "title": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "version": { "type": "string" }, "update": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The version it can update to; null: up to date." } }, "additionalProperties": false }, "Job": { "type": "object", "required": [ "id", "kind", "state", "site", "created_at", "started_at", "finished_at", "steps", "error" ], "properties": { "id": { "type": "string" }, "kind": { "type": "string" }, "state": { "type": "string", "enum": [ "queued", "running", "done", "failed" ] }, "site": { "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "started_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "steps": { "type": "array", "items": { "type": "object", "required": [ "name", "ok", "detail" ], "properties": { "name": { "type": "string" }, "ok": { "type": "boolean" }, "detail": { "oneOf": [ { "type": "string" }, { "type": "null" }, { "type": "array", "items": { "type": "object", "required": [ "name", "from", "to", "status" ], "properties": { "name": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "status": { "type": "string" } }, "additionalProperties": false } } ] } }, "additionalProperties": false } }, "error": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Long work runs on the server as a job: follow it with GET /api/v1/account/services/{id}/jobs?job={id}." }, "Mailbox": { "type": "object", "required": [ "address", "domain", "used_mb", "quota_mb", "suspended_login", "suspended_incoming" ], "properties": { "address": { "type": "string" }, "domain": { "type": "string" }, "used_mb": { "oneOf": [ { "type": "number" }, { "type": "null" } ] }, "quota_mb": { "oneOf": [ { "type": "integer", "description": "null: no limit." }, { "type": "null" } ] }, "suspended_login": { "type": "boolean" }, "suspended_incoming": { "type": "boolean" } }, "additionalProperties": false }, "Forwarder": { "type": "object", "required": [ "address", "to" ], "properties": { "address": { "type": "string" }, "to": { "type": "string" } }, "additionalProperties": false }, "MailSettings": { "type": "object", "required": [ "username", "imap", "pop3", "smtp" ], "properties": { "username": { "type": "string" }, "imap": { "$ref": "#/components/schemas/MailServer" }, "pop3": { "$ref": "#/components/schemas/MailServer" }, "smtp": { "$ref": "#/components/schemas/MailServer" } }, "additionalProperties": false, "description": "How mail programs connect." }, "MailServer": { "type": "object", "required": [ "host", "port", "security" ], "properties": { "host": { "type": "string" }, "port": { "type": "integer" }, "security": { "type": "string", "enum": [ "ssl" ] } }, "additionalProperties": false }, "MailAuthentication": { "type": "object", "required": [ "domain", "spf", "dkim", "dmarc" ], "properties": { "domain": { "type": "string" }, "spf": { "$ref": "#/components/schemas/MailCheck" }, "dkim": { "$ref": "#/components/schemas/MailCheck" }, "dmarc": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "The DMARC record of the zone; null: none." } }, "additionalProperties": false }, "MailCheck": { "type": "object", "required": [ "state", "current", "expected" ], "properties": { "state": { "oneOf": [ { "type": "string" }, { "type": "null" } ], "description": "VALID, or what cPanel found wrong." }, "current": { "type": "array", "items": { "type": "string" } }, "expected": { "oneOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false }, "Terms": { "type": "object", "required": [ "version", "url", "url_fr" ], "properties": { "version": { "type": "string", "description": "Send it as accept_terms once the customer accepted these terms." }, "url": { "type": "string", "format": "uri", "description": "The terms, in English." }, "url_fr": { "type": "string", "format": "uri", "description": "The terms, in French." } }, "additionalProperties": false, "description": "Ex2's terms of service, by version: it changes whenever they do." }, "DomainField": { "type": "object", "required": [ "name", "type", "options", "required", "description" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "choice", "boolean" ] }, "options": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "required": { "type": "boolean" }, "description": { "type": "string" } }, "additionalProperties": false, "description": "An extra field the registry asks for, sent in order_domain's fields by name." }, "ActionRequired": { "type": "object", "required": [ "code", "who", "message", "url", "resume" ], "properties": { "code": { "type": "string", "enum": [ "pay_invoice", "manage_payment_methods", "update_profile", "get_transfer_code", "use_control_panel" ] }, "who": { "type": "string", "enum": [ "customer" ] }, "message": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "Where the customer does it, in the client area." }, "resume": { "type": "string", "description": "How to continue afterwards." } }, "additionalProperties": false, "description": "A step only the customer can take, and how to go on after it." }, "NewPlan": { "type": "object", "required": [ "id", "product", "billing_cycle", "recurring_amount" ], "properties": { "id": { "type": "string", "description": "The plan's id in the catalogue API." }, "product": { "type": "string" }, "billing_cycle": { "type": "string" }, "recurring_amount": { "oneOf": [ { "type": "number", "description": "In the account's currency." }, { "type": "null" } ] } }, "additionalProperties": false } } } }