{"openapi":"3.1.0","info":{"title":"ResellerHQ API","version":"2026-10-07","description":"Buy and manage phone numbers, domains and mailbox licences on behalf of your customers. Amounts are integers in minor units (US cents). Authenticate with `Authorization: Bearer <API key>`."},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from the Developers page. `rhq_test_` keys reach the sandbox, `rhq_live_` keys the live side."}},"schemas":{}},"paths":{"/v1/account":{"get":{"operationId":"getAccount","summary":"Get the account","tags":["Account"],"description":"The account this API key belongs to, with its environment, the product lines it can order and its wallet.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Northwind Telecom"]},"slug":{"type":"string","examples":["northwind"]},"status":{"type":"string","enum":["active","suspended"]},"environment":{"type":"string","enum":["live","sandbox"],"examples":["sandbox"],"description":"Sandbox accounts use a test provider and test funds"},"sandbox":{"type":"boolean","description":"Shorthand for `environment === \"sandbox\"`"},"products":{"type":"object","properties":{"numbers":{"type":"boolean"},"domains":{"type":"boolean"},"licences":{"type":"boolean"}},"required":["numbers","domains","licences"],"additionalProperties":false,"description":"Which product lines this account can order in its environment"},"wallet":{"type":"object","properties":{"available":{"type":"integer","examples":[8800],"description":"Spendable balance in minor units"},"held":{"type":"integer","examples":[0],"description":"Reserved for orders in progress"},"currency":{"type":"string","enum":["USD"]}},"required":["available","held","currency"],"additionalProperties":false},"billing":{"type":"object","properties":{"legalName":{"examples":["Northwind Telecom Ltd"],"description":"Printed on invoices instead of your account name, when the two differ","type":["string","null"]},"addressLines":{"type":"array","items":{"type":"string"},"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"Printed under the legal name, line by line"},"taxId":{"examples":["12-3456789"],"type":["string","null"]},"billingEmail":{"examples":["billing@northwind.example"],"type":["string","null"]},"defaultDueDays":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[14],"description":"`dueInDays` for a new invoice when none is given. Null, 14 days"},"defaultTaxBps":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[2000],"description":"`taxBps` for a new invoice when none is given. Null, no tax"},"invoiceNote":{"examples":["Thank you for your business"],"description":"`note` for a new invoice when none is given","type":["string","null"]}},"required":["legalName","addressLines","taxId","billingEmail","defaultDueDays","defaultTaxBps","invoiceNote"],"additionalProperties":false,"description":"How you are identified on invoices, and the defaults for a new one"},"domains":{"type":"object","properties":{"defaultRegistrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant every order falls back to, absent a per-order one. Null until set, and then an order that sends none of its own is refused"},"privacyByDefault":{"type":"boolean","description":"New registrations get WHOIS privacy wherever the ending offers it. An ending that does not offer it is registered without it rather than refused"}},"required":["defaultRegistrant","privacyByDefault"],"additionalProperties":false},"member":{"anyOf":[{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin","finance","support","read-only"],"examples":["admin"]},"permissions":{"type":"array","items":{"type":"string","enum":["account.read","account.manage","wallet.read","customer.read","customer.manage","order.read","product.read","number.manage","domain.manage","licence.manage","pricing.read","pricing.manage","sale.read","invoice.read","invoice.manage","webhook.read","webhook.manage","apikey.read","apikey.manage","sandbox.use","team.read","team.manage"]},"description":"Every permission this role holds, in the order the docs table prints them"}},"required":["role","permissions"],"additionalProperties":false},{"type":"null"}],"description":"The signed-in colleague's role and what it allows, for the dashboard to gate its navigation on the same matrix the API enforces. `null` for an API key, which belongs to the account rather than to a person"}},"required":["id","name","slug","status","environment","sandbox","products","wallet","billing","domains","member"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/account/billing":{"patch":{"operationId":"updateAccountBilling","summary":"Update billing details","tags":["Account"],"description":"How your account is identified on invoices, and the defaults a new invoice falls back to when `dueInDays`, `taxBps` or `note` is not given. Send only what changes; `null` clears a field. Live and sandbox keep their own.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"legalName":{"examples":["Northwind Telecom Ltd"],"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"addressLines":{"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"The full new list, replacing any you had. At most 4 lines","anyOf":[{"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"taxId":{"examples":["12-3456789"],"anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]},"billingEmail":{"examples":["billing@northwind.example"],"anyOf":[{"type":"string","maxLength":254,"format":"email"},{"type":"null"}]},"defaultDueDays":{"examples":[14],"description":"`dueInDays` for a new invoice when none is given","anyOf":[{"type":"integer","minimum":0,"maximum":365},{"type":"null"}]},"defaultTaxBps":{"examples":[2000],"description":"`taxBps` for a new invoice when none is given","anyOf":[{"type":"integer","minimum":0,"maximum":10000},{"type":"null"}]},"invoiceNote":{"examples":["Thank you for your business"],"description":"`note` for a new invoice when none is given","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]}}}}}},"responses":{"200":{"description":"How you are identified on invoices, and the defaults for a new one","content":{"application/json":{"schema":{"description":"How you are identified on invoices, and the defaults for a new one","type":"object","properties":{"legalName":{"examples":["Northwind Telecom Ltd"],"description":"Printed on invoices instead of your account name, when the two differ","type":["string","null"]},"addressLines":{"type":"array","items":{"type":"string"},"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"Printed under the legal name, line by line"},"taxId":{"examples":["12-3456789"],"type":["string","null"]},"billingEmail":{"examples":["billing@northwind.example"],"type":["string","null"]},"defaultDueDays":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[14],"description":"`dueInDays` for a new invoice when none is given. Null, 14 days"},"defaultTaxBps":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[2000],"description":"`taxBps` for a new invoice when none is given. Null, no tax"},"invoiceNote":{"examples":["Thank you for your business"],"description":"`note` for a new invoice when none is given","type":["string","null"]}},"required":["legalName","addressLines","taxId","billingEmail","defaultDueDays","defaultTaxBps","invoiceNote"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/account/domains":{"patch":{"operationId":"updateAccountDomains","summary":"Update domain-order settings","tags":["Account"],"description":"The registrant every order falls back to, absent a per-order one; `POST /domains` can still send its own for a single order, and is refused with `registrant_required` when there is neither. `null` clears it. Changing any field of a contact already stored drops the registrar's handle and validation for it; sending back the exact same contact keeps them. `privacyByDefault` adds WHOIS privacy to new registrations wherever the ending offers it. Live and sandbox keep their own.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"defaultRegistrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"}},"required":["name","email","phone","address","city","postalCode","country"],"description":"Who the domain is registered to"},{"type":"null"}]},"privacyByDefault":{"type":"boolean","description":"New registrations get WHOIS privacy wherever the ending offers it. An ending that does not offer it is registered without it rather than refused"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"defaultRegistrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant every order falls back to, absent a per-order one. Null until set, and then an order that sends none of its own is refused"},"privacyByDefault":{"type":"boolean","description":"New registrations get WHOIS privacy wherever the ending offers it. An ending that does not offer it is registered without it rather than refused"}},"required":["defaultRegistrant","privacyByDefault"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/wallet":{"get":{"operationId":"getWallet","summary":"Get the balance","tags":["Wallet"],"description":"What you can spend now, and what is reserved for orders in progress.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"available":{"type":"integer","examples":[8800],"description":"Spendable balance in minor units"},"held":{"type":"integer","examples":[0],"description":"Reserved for orders in progress"},"currency":{"type":"string","enum":["USD"]}},"required":["available","held","currency"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/wallet/transactions":{"get":{"operationId":"listWalletTransactions","summary":"List transactions","tags":["Wallet"],"description":"Every movement of the wallet, newest first.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string","enum":["topup","hold","capture","release","refund"]},"in":"query","name":"kind","required":false}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["txn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"kind":{"type":"string","enum":["topup","hold","capture","release","refund"],"examples":["hold"]},"amount":{"type":"integer","examples":[-1200],"description":"Change to the available balance; negative when funds leave it"},"reference":{"anyOf":[{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},{"type":"null"}],"examples":[{"type":"hold","id":"hld_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"}],"description":"What this movement was for"},"memo":{"examples":[null],"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","kind","amount","reference","memo","createdAt"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/customers":{"post":{"operationId":"createCustomer","summary":"Create a customer","tags":["Customers"],"description":"A customer is someone you sell to. Pass its id when ordering to keep track of who has what.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","examples":["jo@northwind.example"]},"name":{"examples":["Jo Bloggs"],"type":"string","maxLength":200},"externalId":{"examples":["crm-1042"],"description":"Your own reference for this customer","type":"string","maxLength":200},"addressLines":{"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"Printed under the customer name on their invoices, line by line. At most 4 lines","maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},"taxId":{"examples":["12-3456789"],"description":"Printed on this customer's invoices","type":"string","minLength":1,"maxLength":40},"priceListId":{"description":"The list this customer is charged from. Unset, your default list","type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]}},"required":["email"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind.example"]},"name":{"examples":["Jo Bloggs"],"type":["string","null"]},"externalId":{"examples":["crm-1042"],"description":"Your own reference for this customer","type":["string","null"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"examples":[null],"description":"The price list this customer is charged from; null is your default list"},"contractRules":{"type":"integer","examples":[2],"description":"How many prices are agreed with this customer alone, beating their price list"},"addressLines":{"type":"array","items":{"type":"string"},"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"Printed under the customer name on their invoices, line by line"},"taxId":{"examples":["12-3456789"],"description":"Printed on this customer's invoices","type":["string","null"]},"registrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant a domain ordered for this customer falls back to, absent a per-order one, ahead of your account's default. Null until set"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","email","name","externalId","priceListId","contractRules","addressLines","taxId","registrant","createdAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `customer_exists`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `customer_exists`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"customer_exists","message":"A customer with this email already exists","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"get":{"operationId":"listCustomers","summary":"List customers","tags":["Customers"],"parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"q","required":false,"description":"Text to look for in the name, email or your reference"},{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"priceListId","required":false,"description":"Only customers charged from this list. Your default list also covers the customers with no list of their own"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind.example"]},"name":{"examples":["Jo Bloggs"],"type":["string","null"]},"externalId":{"examples":["crm-1042"],"description":"Your own reference for this customer","type":["string","null"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"examples":[null],"description":"The price list this customer is charged from; null is your default list"},"contractRules":{"type":"integer","examples":[2],"description":"How many prices are agreed with this customer alone, beating their price list"},"addressLines":{"type":"array","items":{"type":"string"},"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"Printed under the customer name on their invoices, line by line"},"taxId":{"examples":["12-3456789"],"description":"Printed on this customer's invoices","type":["string","null"]},"registrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant a domain ordered for this customer falls back to, absent a per-order one, ahead of your account's default. Null until set"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","email","name","externalId","priceListId","contractRules","addressLines","taxId","registrant","createdAt"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/customers/{id}":{"get":{"operationId":"getCustomer","summary":"Get a customer","tags":["Customers"],"parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind.example"]},"name":{"examples":["Jo Bloggs"],"type":["string","null"]},"externalId":{"examples":["crm-1042"],"description":"Your own reference for this customer","type":["string","null"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"examples":[null],"description":"The price list this customer is charged from; null is your default list"},"contractRules":{"type":"integer","examples":[2],"description":"How many prices are agreed with this customer alone, beating their price list"},"addressLines":{"type":"array","items":{"type":"string"},"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"Printed under the customer name on their invoices, line by line"},"taxId":{"examples":["12-3456789"],"description":"Printed on this customer's invoices","type":["string","null"]},"registrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant a domain ordered for this customer falls back to, absent a per-order one, ahead of your account's default. Null until set"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","email","name","externalId","priceListId","contractRules","addressLines","taxId","registrant","createdAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"patch":{"operationId":"updateCustomer","summary":"Update a customer","tags":["Customers"],"description":"Changes the name, your reference, the price list, the billing address, the tax number or the registrant. Send only what changes. `registrant` falls back ahead of your account default on a domain ordered for this customer with no contact of its own; `null` clears it. Changing any field of a registrant already stored drops the registrar's handle and validation for it; sending back the exact same contact keeps them.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"externalId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}]},"priceListId":{"description":"`null` puts the customer back on your default list","anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"addressLines":{"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"The full new list, replacing any you had. At most 4 lines","anyOf":[{"maxItems":4,"type":"array","items":{"type":"string","minLength":1,"maxLength":120}},{"type":"null"}]},"taxId":{"examples":["12-3456789"],"anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]},"registrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"}},"required":["name","email","phone","address","city","postalCode","country"],"description":"Who the domain is registered to"},{"type":"null"}]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind.example"]},"name":{"examples":["Jo Bloggs"],"type":["string","null"]},"externalId":{"examples":["crm-1042"],"description":"Your own reference for this customer","type":["string","null"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"examples":[null],"description":"The price list this customer is charged from; null is your default list"},"contractRules":{"type":"integer","examples":[2],"description":"How many prices are agreed with this customer alone, beating their price list"},"addressLines":{"type":"array","items":{"type":"string"},"examples":[["1 Market Street","San Francisco, CA 94105"]],"description":"Printed under the customer name on their invoices, line by line"},"taxId":{"examples":["12-3456789"],"description":"Printed on this customer's invoices","type":["string","null"]},"registrant":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant a domain ordered for this customer falls back to, absent a per-order one, ahead of your account's default. Null until set"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","email","name","externalId","priceListId","contractRules","addressLines","taxId","registrant","createdAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers/options":{"get":{"operationId":"getNumberOptions","summary":"List ordering options","tags":["Numbers"],"description":"The countries, products, durations and carriers this account can order.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"examples":[["GB","US"]]},"products":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"object","properties":{"durations":{"type":"array","items":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"}},"maxQuantity":{"type":"integer"}},"required":["durations","maxQuantity"],"additionalProperties":false},"examples":[{"any_service":{"durations":["12h","1d","7d","30d"],"maxQuantity":10},"single_service":{"durations":["7d","30d"],"maxQuantity":1}}],"description":"The durations and largest order each product allows, by product"},"carriers":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"array","items":{"type":"string"}},"examples":[{"US":["att","tmobile"]}],"description":"Carriers you can ask for, by country"},"inboundVoice":{"type":"boolean","description":"Whether numbers that take calls are on offer"}},"required":["countries","products","carriers","inboundVoice"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers/offers":{"get":{"operationId":"listNumberOffers","summary":"List offers","tags":["Numbers"],"description":"Your price for each duration, for a country and product. For `single_service` there is one offer per service. With `customerId`, each price also says what that customer pays.","parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"example":"US","in":"query","name":"country","required":true,"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"schema":{"default":"any_service","type":"string","enum":["any_service","single_service"]},"in":"query","name":"product","required":false,"description":"any_service receives SMS from anyone; single_service is locked to one sender"},{"schema":{"type":"string"},"in":"query","name":"service","required":false,"description":"Only this service, for single_service"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false,"description":"Also return what this customer pays for each price"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[{"id":"whatsapp","name":"WhatsApp"}],"description":"The service a single_service offer is locked to","type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"prices":{"type":"array","items":{"type":"object","properties":{"duration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"},"amount":{"type":"integer","examples":[1200],"description":"Your price, in minor units"},"currency":{"type":"string","enum":["USD"]},"customerPrice":{"examples":[1500],"description":"What the customer pays for a first purchase of one number, in `customerCurrency`. Only when you ask with `customerId`","type":"integer"},"customerCurrency":{"examples":["USD"],"type":"string"}},"required":["duration","amount","currency"],"additionalProperties":false}}},"required":["country","product","prices"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers/orders":{"post":{"operationId":"createNumberOrder","summary":"Create an order","tags":["Numbers"],"description":"Charges your wallet and returns the order with its numbers. Send an Idempotency-Key header so a retry can never buy twice. Check `status`: an order can be `failed` (nothing charged) or still `provisioning` when this returns.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"default":"any_service","type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"description":"Service id from the offers list; required for single_service","type":"string","minLength":1,"maxLength":40},"duration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"},"quantity":{"default":1,"description":"How many numbers to buy","type":"integer","minimum":1,"maximum":50},"autoRenew":{"default":false,"description":"Extend each number shortly before it ends","type":"boolean"},"carrier":{"description":"A carrier from the options list, where the country offers a choice","type":"string","maxLength":20},"receiveCalls":{"description":"Ask for numbers that also take calls, where `inboundVoice` is on offer","type":"boolean"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"Required: every purchase belongs to one of your customers"}},"required":["country","duration","customerId"]}}}},"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"status":{"type":"string","enum":["created","purchasing","provisioning","completed","failed","needs_reconciliation"],"examples":["completed"],"description":"completed: all numbers delivered. failed: nothing charged. provisioning: the carrier is still assigning some numbers. needs_reconciliation: being verified with the carrier."},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"type":["string","null"]},"duration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"},"quantity":{"type":"integer","examples":[1]},"fulfilledCount":{"type":"integer","examples":[1],"description":"Numbers delivered so far"},"autoRenew":{"type":"boolean"},"unitPrice":{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},"totalPrice":{"type":"integer","examples":[1200],"description":"Charged for the numbers delivered, in minor units"},"currency":{"type":"string","enum":["USD"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"Why the order failed, when it did"},"numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","status","customerId","country","product","service","duration","quantity","fulfilledCount","autoRenew","unitPrice","totalPrice","currency","failure","numbers","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"402":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","content":{"application/json":{"schema":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"insufficient_funds","message":"Wallet balance is too low for this purchase","requestId":"req-4f"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended` or `numbers_disabled`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended` or `numbers_disabled`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"idempotency_in_progress","message":"A request with this key is still being processed","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `no_offer`, `service_required`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `no_offer`, `service_required`, or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"no_offer","message":"No provider currently offers this combination","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"get":{"operationId":"listNumberOrders","summary":"List orders","tags":["Numbers"],"description":"Orders with their numbers, newest first.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string","enum":["completed","failed","open"]},"in":"query","name":"status","required":false,"description":"`open` is every order still being placed, assigned or confirmed"},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"example":"US","in":"query","name":"country","required":false,"description":"ISO 3166-1 alpha-2 country code, for example US or GB"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"status":{"type":"string","enum":["created","purchasing","provisioning","completed","failed","needs_reconciliation"],"examples":["completed"],"description":"completed: all numbers delivered. failed: nothing charged. provisioning: the carrier is still assigning some numbers. needs_reconciliation: being verified with the carrier."},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"type":["string","null"]},"duration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"},"quantity":{"type":"integer","examples":[1]},"fulfilledCount":{"type":"integer","examples":[1],"description":"Numbers delivered so far"},"autoRenew":{"type":"boolean"},"unitPrice":{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},"totalPrice":{"type":"integer","examples":[1200],"description":"Charged for the numbers delivered, in minor units"},"currency":{"type":"string","enum":["USD"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"Why the order failed, when it did"},"numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","status","customerId","country","product","service","duration","quantity","fulfilledCount","autoRenew","unitPrice","totalPrice","currency","failure","numbers","createdAt","updatedAt"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers/orders/{id}":{"get":{"operationId":"getNumberOrder","summary":"Get an order","tags":["Numbers"],"parameters":[{"schema":{"type":"string"},"example":"ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"status":{"type":"string","enum":["created","purchasing","provisioning","completed","failed","needs_reconciliation"],"examples":["completed"],"description":"completed: all numbers delivered. failed: nothing charged. provisioning: the carrier is still assigning some numbers. needs_reconciliation: being verified with the carrier."},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"type":["string","null"]},"duration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"},"quantity":{"type":"integer","examples":[1]},"fulfilledCount":{"type":"integer","examples":[1],"description":"Numbers delivered so far"},"autoRenew":{"type":"boolean"},"unitPrice":{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},"totalPrice":{"type":"integer","examples":[1200],"description":"Charged for the numbers delivered, in minor units"},"currency":{"type":"string","enum":["USD"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"Why the order failed, when it did"},"numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","status","customerId","country","product","service","duration","quantity","fulfilledCount","autoRenew","unitPrice","totalPrice","currency","failure","numbers","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers":{"get":{"operationId":"listNumbers","summary":"List numbers","tags":["Numbers"],"description":"The numbers you hold or have held, newest first.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string","enum":["active","expired","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false},{"schema":{"type":"string","pattern":"^[A-Z]{2}$"},"example":"US","in":"query","name":"country","required":false,"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"schema":{"type":"string"},"in":"query","name":"autoRenew","required":false,"description":"`true` or `false`"},{"schema":{"type":"string","maxLength":40},"in":"query","name":"q","required":false,"description":"Digits to look for anywhere in the number, for example its last four"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers/{id}":{"get":{"operationId":"getNumber","summary":"Get a number","tags":["Numbers"],"parameters":[{"schema":{"type":"string"},"example":"num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"patch":{"operationId":"updateNumber","summary":"Update a number","tags":["Numbers"],"description":"Change the nickname, the renewal settings or the price fixed for the customer. Fields you leave out stay as they are.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nickname":{"examples":["Support line"],"description":"Your own label for the number; `null` clears it","anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"autoRenew":{"type":"boolean"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"},"customerPrice":{"examples":[1999],"description":"What the customer pays for one unit of this item from now on, in minor units of their list's currency. It beats their contract and list prices. `null` clears it","anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers/{id}/renew":{"post":{"operationId":"renewNumber","summary":"Renew a number","tags":["Numbers"],"description":"Adds time to the end of the rental and charges your wallet.","requestBody":{"required":true,"content":{"application/json":{"schema":{"default":{},"type":"object","properties":{"duration":{"description":"How long to add. Defaults to the number's `renewDuration`","type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"402":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","content":{"application/json":{"schema":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"insufficient_funds","message":"Wallet balance is too low for this purchase","requestId":"req-4f"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended` or `numbers_disabled`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended` or `numbers_disabled`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `rental_not_active`, `rental_busy`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `rental_not_active`, `rental_busy`, or `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rental_not_active","message":"This number is expired","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `renewal_unavailable` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `renewal_unavailable` or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"renewal_unavailable","message":"This number cannot be renewed for that length","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `renewal_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `renewal_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"renewal_failed","message":"The provider could not renew this number","requestId":"req-4f"}}}}}}},"/v1/numbers/{id}/cancel":{"post":{"operationId":"cancelNumber","summary":"Cancel a number","tags":["Numbers"],"description":"Only possible shortly after purchase and before the number has received a message.","parameters":[{"schema":{"type":"string"},"example":"num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `not_cancellable`, `rental_busy`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `not_cancellable`, `rental_busy`, or `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_cancellable","message":"This number has already received messages","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"idempotency_key_reused","message":"This Idempotency-Key was used with a different request body","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/numbers/{id}/messages":{"get":{"operationId":"listNumberMessages","summary":"List messages","tags":["Numbers"],"description":"The SMS a number has received, newest first.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string"},"in":"query","name":"refresh","required":false,"description":"Check the carrier for new messages before answering"},{"schema":{"type":"string"},"example":"num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["msg_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"numberId":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"sender":{"type":"string","examples":["WhatsApp"]},"body":{"type":"string","examples":["Your code is 428-113"]},"receivedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","numberId","sender","body","receivedAt"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/domains/search":{"get":{"operationId":"searchDomains","summary":"Search for a domain","tags":["Domains"],"description":"Checks one name across every ending on offer, with your price for each. With `customerId`, each also says what that customer pays. A premium name is left out until it can be priced properly, and one the registrar could not check comes back `unknown`.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":253},"example":"northwind-telecom","in":"query","name":"query","required":true,"description":"A bare name, or a full domain to check that one ending first"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false,"description":"Also return what this customer pays for a first purchase"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","examples":["northwind-telecom.com"]},"available":{"type":"boolean"},"price":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"unknown":{"description":"Set when the registrar could not answer for this ending; try again shortly","type":"boolean"},"customerPrice":{"examples":[1799],"description":"What the customer pays for one unit of a first purchase, in `customerCurrency`. Only when you ask with `customerId`","anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}]},"customerCurrency":{"examples":["USD"],"type":"string"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[499],"description":"Your price per year for WHOIS privacy on this ending, in minor units. Null when this ending does not offer privacy"},"customerPrivacyPrice":{"examples":[599],"description":"What the customer pays per year for WHOIS privacy on this ending, in `customerCurrency`. Only when you ask with `customerId`, and null when this ending does not offer privacy","anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}]}},"required":["domain","available","price","privacyPrice"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/domains/check":{"post":{"operationId":"checkDomains","summary":"Check domains","tags":["Domains"],"description":"For buying several at once. A name that is malformed or whose ending is not on offer comes back unavailable, with a null price, as does a premium name or one the registrar could not check.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"minItems":1,"maxItems":100,"type":"array","items":{"type":"string","minLength":1,"maxLength":253},"examples":[["northwind-telecom.com","northwind.io"]]},"customerId":{"description":"Also return what this customer pays for a first purchase","type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]}},"required":["domains"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","examples":["northwind-telecom.com"]},"available":{"type":"boolean"},"price":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"description":"Price per year, or null when not on offer"},"premium":{"description":"Set when this is a premium name, not sellable here yet","type":"boolean"},"unknown":{"description":"Set when the registrar could not answer; try again shortly","type":"boolean"},"customerPrice":{"examples":[1799],"description":"What the customer pays for one unit of a first purchase, in `customerCurrency`. Only when you ask with `customerId`","anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}]},"customerCurrency":{"examples":["USD"],"type":"string"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[499],"description":"Your price per year for WHOIS privacy on this ending, in minor units. Null when this ending does not offer privacy"},"customerPrivacyPrice":{"examples":[599],"description":"What the customer pays per year for WHOIS privacy on this ending, in `customerCurrency`. Only when you ask with `customerId`, and null when this ending does not offer privacy","anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}]}},"required":["domain","available","price","privacyPrice"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/domains":{"post":{"operationId":"registerDomain","summary":"Register a domain","tags":["Domains"],"description":"Charges your wallet for the years asked for, plus WHOIS privacy for those years when it is on. Send an Idempotency-Key header so a retry can never register twice. The registrar can answer `pending`: the domain comes back with `status: \"pending\"` and the charge stays held until it finishes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253,"examples":["northwind-telecom.com"]},"years":{"description":"How many years. Defaults to 1","type":"integer","minimum":1,"maximum":10},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"Required: every purchase belongs to one of your customers"},"contact":{"description":"Who to register the domain to. A registrant is required: send one here, or store one on the customer, or set a default registrant in your account settings. Absent, it falls back to the customer's registrant, then your account's default","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"}},"required":["name","email","phone","address","city","postalCode","country"]},"privacy":{"description":"Add WHOIS privacy. Absent, your account's default decides. An ending that does not offer privacy is refused","type":"boolean"}},"required":["domain","customerId"]}}}},"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"402":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","content":{"application/json":{"schema":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"insufficient_funds","message":"Wallet balance is too low for this purchase","requestId":"req-4f"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_taken`, `domain_owned`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_taken`, `domain_owned`, or `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_taken","message":"This domain is already registered","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `unsupported_tld`, `premium_domain`, `not_available`, `registrant_required`, `unsupported_period`, `privacy_unavailable`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `unsupported_tld`, `premium_domain`, `not_available`, `registrant_required`, `unsupported_period`, `privacy_unavailable`, or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unsupported_tld","message":"This ending is not on offer","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}}}}}},"get":{"operationId":"listDomains","summary":"List domains","tags":["Domains"],"description":"The domains you have registered, newest first.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"]},"in":"query","name":"status","required":false,"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false,"description":"Only domains bought for this customer"},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"q","required":false,"description":"Text to look for anywhere in the domain name"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/domains/{id}":{"get":{"operationId":"getDomain","summary":"Get a domain","tags":["Domains"],"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"patch":{"operationId":"updateDomain","summary":"Update a domain","tags":["Domains"],"description":"Changes the nameservers, the contacts, the transfer lock, the registrar hold, WHOIS privacy or the price fixed for the customer. Send only the fields you want to change. Nothing is charged. Answers `202` instead of `200` when the registrar accepted the change but has not finished it yet; the body is the domain as it stands now, before that change lands.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"nameservers":{"description":"The full new list; `null` goes back to the registrar's own","anyOf":[{"minItems":2,"maxItems":6,"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]}},{"type":"null"}]},"contact":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"}},"required":["name","email","phone","address","city","postalCode","country"],"description":"Who the domain is registered to"},"contacts":{"description":"Only the roles given are changed; `null` goes back to the registrant","type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"}},"required":["name","email","phone","address","city","postalCode","country"],"description":"Who the domain is registered to"},{"type":"null"}]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"}},"required":["name","email","phone","address","city","postalCode","country"],"description":"Who the domain is registered to"},{"type":"null"}]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"}},"required":["name","email","phone","address","city","postalCode","country"],"description":"Who the domain is registered to"},{"type":"null"}]}}},"locked":{"type":"boolean"},"suspended":{"description":"Put the domain on hold, or take it off hold. Nothing is charged: a suspended domain stays registered and still renews","type":"boolean"},"privacy":{"description":"Turn WHOIS privacy on or off. Nothing is charged now either way: privacy is charged from the next renewal while it is on, and turning it off refunds nothing","type":"boolean"},"customerPrice":{"examples":[1999],"description":"What the customer pays for one unit of this item from now on, in minor units of their list's currency. It beats their contract and list prices. `null` clears it","anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}}}},"202":{"description":"Accepted: the registrar has not finished this change yet","content":{"application/json":{"schema":{"description":"Accepted: the registrar has not finished this change yet","type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `domain_busy`, or `registrar_refused`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `domain_busy`, or `registrar_refused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_nameserver`, `not_available`, or `privacy_unavailable`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_nameserver`, `not_available`, or `privacy_unavailable`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"invalid_nameserver","message":"Each nameserver must be a hostname, like ns1.example.com","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}}}}}},"delete":{"operationId":"deleteDomain","summary":"Delete a domain","tags":["Domains"],"description":"Gives the registration up at the registrar. The name stops being yours and goes back to the registry; it cannot be undone from here. Inside the registry's add grace period the registration charge alone is credited back to your wallet — not WHOIS privacy, and never a renewal; quote it first with `GET /v1/domains/{id}/delete-quote`. The domain stays on your account as a record, with `status: \"deleted\"`.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_not_deletable`, `domain_busy`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_not_deletable`, `domain_busy`, or `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_not_deletable","message":"This domain cannot be deleted as it stands","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `delete_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `delete_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"delete_failed","message":"The registrar could not delete this domain","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/renew":{"post":{"operationId":"renewDomain","summary":"Renew a domain","tags":["Domains"],"description":"Adds years to the end of the registration and charges your wallet, including WHOIS privacy for those years while it is on.","requestBody":{"required":true,"content":{"application/json":{"schema":{"default":{},"type":"object","properties":{"years":{"description":"How many years. Defaults to 1","type":"integer","minimum":1,"maximum":10}}}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"402":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","content":{"application/json":{"schema":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"insufficient_funds","message":"Wallet balance is too low for this purchase","requestId":"req-4f"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_busy`, `domain_expired`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_busy`, `domain_expired`, or `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_busy","message":"Another renewal of this domain is in progress","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/auth-code":{"post":{"operationId":"createDomainAuthCode","summary":"Get a transfer code","tags":["Domains"],"description":"Generates a fresh transfer (auth) code and shows it once: we never store it, and it never appears in a list or a webhook. The domain must have its transfer lock off first; this never turns it off for you. A new code replaces the old one.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"The transfer code, shown once","content":{"application/json":{"schema":{"description":"The transfer code, shown once","type":"object","properties":{"authCode":{"type":"string","description":"The transfer code. Shown once; we keep no copy"}},"required":["authCode"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_locked` or `domain_expired`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_locked` or `domain_expired`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_locked","message":"Turn the transfer lock off before asking for a transfer code","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `auth_code_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `auth_code_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"auth_code_failed","message":"The registrar could not generate a transfer code","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/restore-quote":{"get":{"operationId":"quoteDomainRestore","summary":"Quote a restore","tags":["Domains"],"description":"What bringing this domain back out of redemption would cost you. A restore costs many times a renewal and the registry usually charges a year with it, so read this before committing. Only a domain in `redemption` can be quoted.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"What a restore of this domain would cost","content":{"application/json":{"schema":{"description":"What a restore of this domain would cost","type":"object","properties":{"cost":{"type":"integer","minimum":0,"examples":[1440],"description":"The restore itself, in minor units"},"renewalYears":{"type":"integer","minimum":0,"examples":[1],"description":"How many years the registry charges along with the restore; 0 for none"},"renewalCost":{"type":"integer","minimum":0,"examples":[1440],"description":"What those years cost, in minor units; 0 when none are charged"},"total":{"type":"integer","minimum":0,"examples":[5276],"description":"What your wallet is charged for the restore, in minor units"},"unknown":{"type":"boolean","description":"Set when the registrar could not price the restore and `total` comes from the catalogue instead. Still chargeable, but the figure may move"}},"required":["cost","renewalYears","renewalCost","total","unknown"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_not_in_redemption`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_not_in_redemption`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_not_in_redemption","message":"Only a domain in redemption can be restored","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/restore":{"post":{"operationId":"restoreDomain","summary":"Restore a domain","tags":["Domains"],"description":"Brings a domain in redemption back and charges your wallet the restore price, including the year the registry charges with it. Quote it first with `GET /v1/domains/{id}/restore-quote`. The domain comes back `active` with its new expiry date.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"402":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","content":{"application/json":{"schema":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"insufficient_funds","message":"Wallet balance is too low for this purchase","requestId":"req-4f"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_busy`, `domain_not_in_redemption`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_busy`, `domain_not_in_redemption`, or `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_busy","message":"Another renewal of this domain is in progress","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `restore_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `restore_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"restore_failed","message":"The registrar could not restore this domain","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/delete-quote":{"get":{"operationId":"quoteDomainDelete","summary":"Quote a delete","tags":["Domains"],"description":"What deleting this domain now would give back. The window is the registry's own add grace period, read from the registrar and measured from the registration: inside it the registration charge alone comes back, and outside it nothing does. WHOIS privacy is not refunded, and neither is any renewal since.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"What deleting this domain now gives back","content":{"application/json":{"schema":{"description":"What deleting this domain now gives back","type":"object","properties":{"refund":{"type":"integer","minimum":0,"examples":[1319],"description":"What your wallet is credited if you delete now, in minor units: the registration charge alone, without WHOIS privacy and without any renewal since. 0 once the window has closed, and for a registry that has none"},"graceEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":["2026-10-12T11:04:31.000Z"],"description":"When the refundable window closes. `null` when this registry has no such window at all, so a delete never refunds anything"}},"required":["refund","graceEndsAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_not_deletable`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_not_deletable`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"domain_not_deletable","message":"This domain cannot be deleted as it stands","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}},"502":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/history":{"get":{"operationId":"listDomainHistory","summary":"List a domain's history","tags":["Domains"],"description":"Everything that was done to this domain, newest first: what it was, when, and who asked for it. The same events a webhook carries, read back per domain — one row per thing done, so putting a domain on hold reads as the hold itself rather than also as a settings change.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["evt_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"type":{"type":"string","examples":["domain.renewed"],"description":"What was done"},"at":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"actor":{"anyOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["user","api_key","system"],"description":"A colleague in the dashboard, an API key, or our own worker"},"label":{"description":"The API key's name, or the colleague's display name. Null when they have set none, and never an email address or anything else personal","type":["string","null"]}},"required":["kind","label"],"additionalProperties":false},{"type":"null"}],"description":"Who did it; null for anything done before we recorded that"},"detail":{"description":"What changed, in words","type":["string","null"]}},"required":["id","type","at","actor","detail"],"additionalProperties":false,"description":"One thing that was done to this domain"}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/licences/plans":{"get":{"operationId":"listLicencePlans","summary":"List plans","tags":["Mailbox licences"],"description":"The plans on offer, with your price per seat per month. With `customerId`, each also says what that customer pays.","parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false,"description":"Also return what this customer pays for a first purchase"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["google-workspace-starter"],"description":"Pass this as `plan` when buying"},"name":{"type":"string","examples":["Workspace Business Starter"]},"vendor":{"type":"string","enum":["google","microsoft"]},"price":{"type":"integer","minimum":0,"examples":[840],"description":"Price per seat per month, in minor units"},"customerPrice":{"examples":[1799],"description":"What the customer pays for one unit of a first purchase, in `customerCurrency`. Only when you ask with `customerId`","anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}]},"customerCurrency":{"examples":["USD"],"type":"string"}},"required":["id","name","vendor","price"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/licences":{"post":{"operationId":"createLicence","summary":"Create a licence","tags":["Mailbox licences"],"description":"Charges your wallet for the first month. Send an Idempotency-Key header so a retry can never buy twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","examples":["google-workspace-starter"],"description":"A plan id from the plans list"},"domain":{"type":"string","minLength":3,"maxLength":253,"examples":["northwind-telecom.com"],"description":"The domain the mailboxes are on"},"seats":{"type":"integer","minimum":1,"maximum":300,"examples":[5]},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"Required: every purchase belongs to one of your customers"}},"required":["plan","domain","seats","customerId"]}}}},"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["lic_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"plan":{"type":"string","examples":["google-workspace-starter"],"description":"A plan id from the plans list"},"planName":{"type":"string","examples":["Workspace Business Starter"]},"vendor":{"type":"string","enum":["google","microsoft"]},"domain":{"type":"string","examples":["northwind-telecom.com"],"description":"The domain the mailboxes are on"},"seats":{"type":"integer","examples":[5]},"status":{"type":"string","enum":["active","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[840],"description":"Price per seat per month, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[4200],"description":"Everything charged for this licence so far, in minor units"},"periodEndsAt":{"type":"string","format":"date-time","examples":["2026-11-07T11:04:31.000Z"],"description":"When the month already paid for ends. The next month is charged then, for every seat"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When the month now due first could not be charged to your wallet. Null when nothing is owed"},"cancelsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When an unpaid licence is cancelled: a week after `unpaidSince`. Add funds before then and the next run renews it. Null when nothing is owed"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","plan","planName","vendor","domain","seats","status","customerId","unitPrice","customerPrice","paidTotal","periodEndsAt","unpaidSince","cancelsAt","createdAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"402":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","content":{"application/json":{"schema":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"insufficient_funds","message":"Wallet balance is too low for this purchase","requestId":"req-4f"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"idempotency_in_progress","message":"A request with this key is still being processed","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `unknown_plan`, `invalid_domain`, `not_available`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `unknown_plan`, `invalid_domain`, `not_available`, or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unknown_plan","message":"This plan is not on offer","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"get":{"operationId":"listLicences","summary":"List licences","tags":["Mailbox licences"],"description":"The licences you hold or have held, newest first.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string","enum":["active","cancelled"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","enum":["google","microsoft"]},"in":"query","name":"vendor","required":false},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false,"description":"Only licences bought for this customer"},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"q","required":false,"description":"Text to look for anywhere in the domain"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["lic_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"plan":{"type":"string","examples":["google-workspace-starter"],"description":"A plan id from the plans list"},"planName":{"type":"string","examples":["Workspace Business Starter"]},"vendor":{"type":"string","enum":["google","microsoft"]},"domain":{"type":"string","examples":["northwind-telecom.com"],"description":"The domain the mailboxes are on"},"seats":{"type":"integer","examples":[5]},"status":{"type":"string","enum":["active","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[840],"description":"Price per seat per month, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[4200],"description":"Everything charged for this licence so far, in minor units"},"periodEndsAt":{"type":"string","format":"date-time","examples":["2026-11-07T11:04:31.000Z"],"description":"When the month already paid for ends. The next month is charged then, for every seat"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When the month now due first could not be charged to your wallet. Null when nothing is owed"},"cancelsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When an unpaid licence is cancelled: a week after `unpaidSince`. Add funds before then and the next run renews it. Null when nothing is owed"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","plan","planName","vendor","domain","seats","status","customerId","unitPrice","customerPrice","paidTotal","periodEndsAt","unpaidSince","cancelsAt","createdAt"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/licences/{id}":{"patch":{"operationId":"updateLicence","summary":"Update a licence","tags":["Mailbox licences"],"description":"Changes the seats or the price fixed for the customer. Added seats are charged a full month each. Removed seats stop at once and are not refunded.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"seats":{"description":"The new total, not the change","type":"integer","minimum":1,"maximum":300,"examples":[5]},"customerPrice":{"examples":[1999],"description":"What the customer pays for one unit of this item from now on, in minor units of their list's currency. It beats their contract and list prices. `null` clears it","anyOf":[{"type":"integer","minimum":0,"maximum":100000000},{"type":"null"}]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"lic_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["lic_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"plan":{"type":"string","examples":["google-workspace-starter"],"description":"A plan id from the plans list"},"planName":{"type":"string","examples":["Workspace Business Starter"]},"vendor":{"type":"string","enum":["google","microsoft"]},"domain":{"type":"string","examples":["northwind-telecom.com"],"description":"The domain the mailboxes are on"},"seats":{"type":"integer","examples":[5]},"status":{"type":"string","enum":["active","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[840],"description":"Price per seat per month, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[4200],"description":"Everything charged for this licence so far, in minor units"},"periodEndsAt":{"type":"string","format":"date-time","examples":["2026-11-07T11:04:31.000Z"],"description":"When the month already paid for ends. The next month is charged then, for every seat"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When the month now due first could not be charged to your wallet. Null when nothing is owed"},"cancelsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When an unpaid licence is cancelled: a week after `unpaidSince`. Add funds before then and the next run renews it. Null when nothing is owed"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","plan","planName","vendor","domain","seats","status","customerId","unitPrice","customerPrice","paidTotal","periodEndsAt","unpaidSince","cancelsAt","createdAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"402":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","content":{"application/json":{"schema":{"description":"The wallet cannot cover this. Nothing was charged. `error` is `insufficient_funds`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"insufficient_funds","message":"Wallet balance is too low for this purchase","requestId":"req-4f"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `licence_busy`, `licence_charge_in_doubt`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `licence_busy`, `licence_charge_in_doubt`, or `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"licence_busy","message":"Another change to this licence is in progress","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/licences/{id}/cancel":{"post":{"operationId":"cancelLicence","summary":"Cancel a licence","tags":["Mailbox licences"],"description":"Ends it now. The month already paid for is not refunded.","parameters":[{"schema":{"type":"string"},"example":"lic_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["lic_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"plan":{"type":"string","examples":["google-workspace-starter"],"description":"A plan id from the plans list"},"planName":{"type":"string","examples":["Workspace Business Starter"]},"vendor":{"type":"string","enum":["google","microsoft"]},"domain":{"type":"string","examples":["northwind-telecom.com"],"description":"The domain the mailboxes are on"},"seats":{"type":"integer","examples":[5]},"status":{"type":"string","enum":["active","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[840],"description":"Price per seat per month, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[4200],"description":"Everything charged for this licence so far, in minor units"},"periodEndsAt":{"type":"string","format":"date-time","examples":["2026-11-07T11:04:31.000Z"],"description":"When the month already paid for ends. The next month is charged then, for every seat"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When the month now due first could not be charged to your wallet. Null when nothing is owed"},"cancelsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When an unpaid licence is cancelled: a week after `unpaidSince`. Add funds before then and the next run renews it. Null when nothing is owed"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","plan","planName","vendor","domain","seats","status","customerId","unitPrice","customerPrice","paidTotal","periodEndsAt","unpaidSince","cancelsAt","createdAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/orders":{"get":{"operationId":"listOrders","summary":"List purchases","tags":["Orders"],"description":"Everything bought across products, newest first: each number order, each domain registered and each block of mailbox licences.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string","enum":["number","domain","licence"]},"in":"query","name":"product","required":false},{"schema":{"type":"string","enum":["completed","failed","open"]},"in":"query","name":"status","required":false,"description":"Domains and licences are recorded once delivered, so they are `completed`"},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"q","required":false,"description":"Text to look for in the domain, or digits of a number"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"product":{"type":"string","enum":["number"]},"id":{"type":"string"},"placedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"order":{"type":"object","properties":{"id":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"status":{"type":"string","enum":["created","purchasing","provisioning","completed","failed","needs_reconciliation"],"examples":["completed"],"description":"completed: all numbers delivered. failed: nothing charged. provisioning: the carrier is still assigning some numbers. needs_reconciliation: being verified with the carrier."},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"type":["string","null"]},"duration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"Length of the rental"},"quantity":{"type":"integer","examples":[1]},"fulfilledCount":{"type":"integer","examples":[1],"description":"Numbers delivered so far"},"autoRenew":{"type":"boolean"},"unitPrice":{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},"totalPrice":{"type":"integer","examples":[1200],"description":"Charged for the numbers delivered, in minor units"},"currency":{"type":"string","enum":["USD"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"Why the order failed, when it did"},"numbers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["num_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["15550100002"],"description":"Digits only, as issued by the carrier"},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},"product":{"type":"string","enum":["any_service","single_service"],"description":"any_service receives SMS from anyone; single_service is locked to one sender"},"service":{"examples":[null],"description":"The one service a single_service number receives from","type":["string","null"]},"status":{"type":"string","enum":["active","expired","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"orderId":{"type":"string","examples":["ord_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"nickname":{"examples":["Support line"],"type":["string","null"]},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-06T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"autoRenew":{"type":"boolean","description":"Whether it is extended shortly before it ends"},"renewDuration":{"type":"string","enum":["12h","1d","7d","30d","180d","365d"],"examples":["30d"],"description":"How long each automatic renewal adds"},"unitPrice":{"type":"integer","examples":[1200],"description":"Price of one rental period, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","examples":[1200],"description":"Amount in minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A price per renewal fixed for the customer on this number alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","examples":[1200],"description":"Everything charged for this number so far, in minor units"},"messageCount":{"type":"integer","examples":[3]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","customerId","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","createdAt"],"additionalProperties":false}},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","status","customerId","country","product","service","duration","quantity","fulfilledCount","autoRenew","unitPrice","totalPrice","currency","failure","numbers","createdAt","updatedAt"],"additionalProperties":false}},"required":["product","id","placedAt","order"],"additionalProperties":false},{"type":"object","properties":{"product":{"type":"string","enum":["domain"]},"id":{"type":"string"},"placedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"domain":{"type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","pending_validation","active","expired","redemption","needs_reconciliation","transferred_out","deleted"],"description":"pending: not yet finished at the registrar. pending_validation: registered and billed, held behind contact validation. active: registered and working. expired: past its expiry date, still renewable. redemption: past the renewal window, only a restore can save it. needs_reconciliation: the last registrar call is unknown. transferred_out: moved away to another registrar; no longer ours to renew or change. deleted: the registration was given up at the registrar and is no longer yours"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"Price per year, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"Everything charged for this domain so far, in minor units"},"registeredAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"expiresAt":{"type":"string","format":"date-time","examples":["2027-10-07T11:04:31.000Z"],"description":"When the registration ends. While `status` is `pending` or `needs_reconciliation` this is only our estimate from the period ordered: the registrar's own date replaces it once the order finishes"},"nameservers":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]},"description":"Where the domain's DNS is served from"},"customNameservers":{"type":"boolean","description":"False while the domain is on the registrar's own nameservers"},"contact":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"description":"The registrant, or null until you set one"},"contacts":{"type":"object","properties":{"admin":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"tech":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]},"billing":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Jo Bloggs"]},"organization":{"type":"string","minLength":1,"maxLength":200,"examples":["Northwind Telecom"]},"email":{"type":"string","maxLength":254,"pattern":"^(?=.{1,64}@)[a-z0-9_\\-+]+(?:\\.[a-z0-9_\\-+]+)*@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+(?:[a-z][a-z0-9-]{0,61}[a-z0-9])$","examples":["jo@northwind.example"]},"phone":{"type":"string","examples":["+1 415 555 0132"]},"address":{"type":"string","minLength":1,"maxLength":300,"examples":["1 Market Street"]},"city":{"type":"string","minLength":1,"maxLength":100,"examples":["San Francisco"]},"state":{"type":"string","minLength":1,"maxLength":100,"examples":["CA"]},"postalCode":{"type":"string","minLength":1,"maxLength":16,"examples":["94105"]},"country":{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code"},"validation":{"description":"The registrar's check on this contact. Absent until the registrar has one; `pending` until it confirms the contact, then `validated`","type":"string","enum":["pending","validated"]}},"required":["name","email","phone","address","city","postalCode","country"],"additionalProperties":false},{"type":"null"}],"examples":[null]}},"required":["admin","tech","billing"],"additionalProperties":false,"description":"The administrative, technical and billing contacts. `null` means the same as the registrant"},"locked":{"type":"boolean","description":"Whether transfers away from us are refused"},"suspended":{"type":"boolean","description":"Whether the domain is on hold at the registrar: it does not resolve, but it is still registered and still renews"},"privacy":{"type":"boolean","description":"Whether WHOIS privacy is on for this domain"},"privacyPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What you pay per year for privacy while it is on, in minor units. Null when privacy is off"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice"],"additionalProperties":false}},"required":["product","id","placedAt","domain"],"additionalProperties":false},{"type":"object","properties":{"product":{"type":"string","enum":["licence"]},"id":{"type":"string"},"placedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"licence":{"type":"object","properties":{"id":{"type":"string","examples":["lic_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"plan":{"type":"string","examples":["google-workspace-starter"],"description":"A plan id from the plans list"},"planName":{"type":"string","examples":["Workspace Business Starter"]},"vendor":{"type":"string","enum":["google","microsoft"]},"domain":{"type":"string","examples":["northwind-telecom.com"],"description":"The domain the mailboxes are on"},"seats":{"type":"integer","examples":[5]},"status":{"type":"string","enum":["active","cancelled"]},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The customer this was bought for, if any"},"unitPrice":{"type":"integer","minimum":0,"examples":[840],"description":"Price per seat per month, in minor units"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"A unit price fixed for the customer on this item alone, in their list's currency. It beats their contract and list. Null when there is none"},"paidTotal":{"type":"integer","minimum":0,"examples":[4200],"description":"Everything charged for this licence so far, in minor units"},"periodEndsAt":{"type":"string","format":"date-time","examples":["2026-11-07T11:04:31.000Z"],"description":"When the month already paid for ends. The next month is charged then, for every seat"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When the month now due first could not be charged to your wallet. Null when nothing is owed"},"cancelsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null],"description":"When an unpaid licence is cancelled: a week after `unpaidSince`. Add funds before then and the next run renews it. Null when nothing is owed"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","plan","planName","vendor","domain","seats","status","customerId","unitPrice","customerPrice","paidTotal","periodEndsAt","unpaidSince","cancelsAt","createdAt"],"additionalProperties":false}},"required":["product","id","placedAt","licence"],"additionalProperties":false}],"description":"One purchase: a number order, a domain registration or a block of licences"}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/price-lists":{"get":{"operationId":"listPriceLists","summary":"List price lists","tags":["Pricing"],"description":"What you charge your customers. Your wallet is always charged the wholesale price; a price list sets what each customer pays you.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Agency"]},"markupBps":{"type":"integer","minimum":0,"maximum":1000000,"examples":[2000],"description":"Markup over wholesale for anything no rule covers, in basis points"},"rounding":{"type":"string","enum":["99","none","00"],"description":"`99` and `00` round worked-out prices up to the next amount ending that way"},"allowBelowCost":{"type":"boolean","description":"False raises any price that would sit under wholesale up to wholesale"},"renewals":{"type":"string","enum":["follow","hold"],"description":"`follow` prices each renewal from the list as it is then; `hold` charges what the customer last paid for that item"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency customers on this list are charged in"},"rate":{"type":"integer","examples":[1000000],"description":"How much of the currency one US dollar buys, in millionths: 920000 is 0.92. Always 1000000 for USD"},"isDefault":{"type":"boolean","description":"The list for customers with none of their own"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"}},"required":["id","product","kind","value"],"additionalProperties":false}},"customers":{"type":"integer","examples":[3],"description":"How many customers are on this list"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","markupBps","rounding","allowBelowCost","renewals","currency","rate","isDefault","rules","customers","createdAt","updatedAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"post":{"operationId":"createPriceList","summary":"Create a price list","tags":["Pricing"],"description":"Your first list becomes the default for every customer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Agency"]},"markupBps":{"default":0,"type":"integer","minimum":0,"maximum":1000000,"examples":[2000],"description":"Markup over wholesale for anything no rule covers, in basis points"},"rounding":{"default":"none","type":"string","enum":["99","none","00"],"description":"`99` and `00` round worked-out prices up to the next amount ending that way"},"allowBelowCost":{"default":false,"type":"boolean"},"renewals":{"default":"follow","type":"string","enum":["follow","hold"],"description":"`follow` prices each renewal from the list as it is then; `hold` charges what the customer last paid for that item"},"currency":{"default":"USD","type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency customers on this list are charged in"},"rate":{"description":"How much of `currency` one US dollar buys, in millionths. Needed for any currency but USD","type":"integer","minimum":10000,"maximum":100000000000,"examples":[1000000]},"isDefault":{"type":"boolean"},"rules":{"default":[],"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"}},"required":["product","kind","value"]}}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Agency"]},"markupBps":{"type":"integer","minimum":0,"maximum":1000000,"examples":[2000],"description":"Markup over wholesale for anything no rule covers, in basis points"},"rounding":{"type":"string","enum":["99","none","00"],"description":"`99` and `00` round worked-out prices up to the next amount ending that way"},"allowBelowCost":{"type":"boolean","description":"False raises any price that would sit under wholesale up to wholesale"},"renewals":{"type":"string","enum":["follow","hold"],"description":"`follow` prices each renewal from the list as it is then; `hold` charges what the customer last paid for that item"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency customers on this list are charged in"},"rate":{"type":"integer","examples":[1000000],"description":"How much of the currency one US dollar buys, in millionths: 920000 is 0.92. Always 1000000 for USD"},"isDefault":{"type":"boolean","description":"The list for customers with none of their own"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"}},"required":["id","product","kind","value"],"additionalProperties":false}},"customers":{"type":"integer","examples":[3],"description":"How many customers are on this list"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","markupBps","rounding","allowBelowCost","renewals","currency","rate","isDefault","rules","customers","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `too_many_price_lists`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `too_many_price_lists`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"too_many_price_lists","message":"An account holds at most 50 price lists","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, `invalid_rate`, or `invalid_currency`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, `invalid_rate`, or `invalid_currency`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/price-lists/{id}":{"get":{"operationId":"getPriceList","summary":"Get a price list","tags":["Pricing"],"parameters":[{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Agency"]},"markupBps":{"type":"integer","minimum":0,"maximum":1000000,"examples":[2000],"description":"Markup over wholesale for anything no rule covers, in basis points"},"rounding":{"type":"string","enum":["99","none","00"],"description":"`99` and `00` round worked-out prices up to the next amount ending that way"},"allowBelowCost":{"type":"boolean","description":"False raises any price that would sit under wholesale up to wholesale"},"renewals":{"type":"string","enum":["follow","hold"],"description":"`follow` prices each renewal from the list as it is then; `hold` charges what the customer last paid for that item"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency customers on this list are charged in"},"rate":{"type":"integer","examples":[1000000],"description":"How much of the currency one US dollar buys, in millionths: 920000 is 0.92. Always 1000000 for USD"},"isDefault":{"type":"boolean","description":"The list for customers with none of their own"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"}},"required":["id","product","kind","value"],"additionalProperties":false}},"customers":{"type":"integer","examples":[3],"description":"How many customers are on this list"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","markupBps","rounding","allowBelowCost","renewals","currency","rate","isDefault","rules","customers","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"patch":{"operationId":"updatePriceList","summary":"Update a price list","tags":["Pricing"],"description":"Send only what changes. `rules` replaces the whole set. New prices apply to purchases and renewals from now on; sales already recorded keep the price they were made at. A change sends a `price_list.updated` event naming the settings that moved and the customers on the list.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Agency"]},"markupBps":{"type":"integer","minimum":0,"maximum":1000000,"examples":[2000],"description":"Markup over wholesale for anything no rule covers, in basis points"},"rounding":{"type":"string","enum":["99","none","00"],"description":"`99` and `00` round worked-out prices up to the next amount ending that way"},"allowBelowCost":{"type":"boolean"},"renewals":{"type":"string","enum":["follow","hold"],"description":"`follow` prices each renewal from the list as it is then; `hold` charges what the customer last paid for that item"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency customers on this list are charged in"},"rate":{"type":"integer","minimum":10000,"maximum":100000000000,"examples":[1000000],"description":"How much of the currency one US dollar buys, in millionths: 920000 is 0.92. Always 1000000 for USD"},"rules":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"}},"required":["product","kind","value"]}},"isDefault":{"description":"Makes this the default list","type":"boolean","enum":[true]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Agency"]},"markupBps":{"type":"integer","minimum":0,"maximum":1000000,"examples":[2000],"description":"Markup over wholesale for anything no rule covers, in basis points"},"rounding":{"type":"string","enum":["99","none","00"],"description":"`99` and `00` round worked-out prices up to the next amount ending that way"},"allowBelowCost":{"type":"boolean","description":"False raises any price that would sit under wholesale up to wholesale"},"renewals":{"type":"string","enum":["follow","hold"],"description":"`follow` prices each renewal from the list as it is then; `hold` charges what the customer last paid for that item"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency customers on this list are charged in"},"rate":{"type":"integer","examples":[1000000],"description":"How much of the currency one US dollar buys, in millionths: 920000 is 0.92. Always 1000000 for USD"},"isDefault":{"type":"boolean","description":"The list for customers with none of their own"},"rules":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"}},"required":["id","product","kind","value"],"additionalProperties":false}},"customers":{"type":"integer","examples":[3],"description":"How many customers are on this list"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","markupBps","rounding","allowBelowCost","renewals","currency","rate","isDefault","rules","customers","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, `invalid_rate`, or `invalid_currency`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, `invalid_rate`, or `invalid_currency`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"delete":{"operationId":"deletePriceList","summary":"Delete a price list","tags":["Pricing"],"description":"Customers on it go back to the default list.","parameters":[{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"204":{"description":"Deleted"},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `default_price_list`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `default_price_list`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"default_price_list","message":"Make another list the default before removing this one","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/price-lists/{id}/impact":{"post":{"operationId":"previewPriceListChange","summary":"Preview a price change","tags":["Pricing"],"description":"Takes the changes you are thinking of making to a list and saves nothing. Says how many customers are on the list and, for up to 50 of the domains, licences and numbers they hold, what one unit of the next renewal costs them now and what it would cost after the change.","requestBody":{"required":true,"content":{"application/json":{"schema":{"default":{},"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Agency"]},"markupBps":{"type":"integer","minimum":0,"maximum":1000000,"examples":[2000],"description":"Markup over wholesale for anything no rule covers, in basis points"},"rounding":{"type":"string","enum":["99","none","00"],"description":"`99` and `00` round worked-out prices up to the next amount ending that way"},"allowBelowCost":{"type":"boolean"},"renewals":{"type":"string","enum":["follow","hold"],"description":"`follow` prices each renewal from the list as it is then; `hold` charges what the customer last paid for that item"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency customers on this list are charged in"},"rate":{"type":"integer","minimum":10000,"maximum":100000000000,"examples":[1000000],"description":"How much of the currency one US dollar buys, in millionths: 920000 is 0.92. Always 1000000 for USD"},"rules":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"}},"required":["product","kind","value"]}},"isDefault":{"description":"Looks at making this the default list: the customers with no list of their own are counted too, at what they pay now","type":"boolean","enum":[true]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"customers":{"type":"integer","examples":[3],"description":"How many customers are on this list"},"items":{"type":"integer","examples":[12],"description":"How many active domains, licences and numbers those customers hold"},"changed":{"type":"integer","examples":[4],"description":"How many of the items in `data` would change price"},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"id":{"type":"string","examples":["dom_01K6Z3M5T8Q2W4E6R8Y0U2I4O6"]},"name":{"type":"string","examples":["northwind-telecom.com"]},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"cost":{"type":"integer","minimum":0,"examples":[1440],"description":"The wholesale price of one unit, in US cents"},"current":{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"examples":[1440],"description":"The wholesale price of one unit, in US cents"},"price":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer pays for one unit, in `currency`"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"ISO 4217 currency code. A price list takes USD, EUR, GBP, CAD, AUD, NZD, CHF, SEK, NOK, DKK, PLN, INR, SGD, HKD, AED, ZAR, BRL or MXN: currencies counted in hundredths"},"priceUsd":{"type":"integer","minimum":0,"examples":[1440],"description":"`price` in US cents at the list's rate"},"ruleId":{"anyOf":[{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The rule that set the price, if one did"},"level":{"type":"string","enum":["override","contract","list","none"],"description":"What set the price: the item's own price (`override`), the customer's contract, their price list, or `none` when you have no list and the customer pays wholesale"},"floored":{"type":"boolean","description":"True when the price was raised to wholesale"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored"],"additionalProperties":false,"description":"What the customer pays for one unit now"},"proposed":{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"examples":[1440],"description":"The wholesale price of one unit, in US cents"},"price":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer pays for one unit, in `currency`"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"ISO 4217 currency code. A price list takes USD, EUR, GBP, CAD, AUD, NZD, CHF, SEK, NOK, DKK, PLN, INR, SGD, HKD, AED, ZAR, BRL or MXN: currencies counted in hundredths"},"priceUsd":{"type":"integer","minimum":0,"examples":[1440],"description":"`price` in US cents at the list's rate"},"ruleId":{"anyOf":[{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The rule that set the price, if one did"},"level":{"type":"string","enum":["override","contract","list","none"],"description":"What set the price: the item's own price (`override`), the customer's contract, their price list, or `none` when you have no list and the customer pays wholesale"},"floored":{"type":"boolean","description":"True when the price was raised to wholesale"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored"],"additionalProperties":false,"description":"What they would pay after the change"}},"required":["type","id","name","customerId","cost","current","proposed"],"additionalProperties":false}}},"required":["customers","items","changed","data"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, `invalid_rate`, or `invalid_currency`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, `invalid_rate`, or `invalid_currency`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/customers/{id}/contract-rules":{"get":{"operationId":"listContractRules","summary":"List contract prices","tags":["Pricing"],"description":"The prices agreed with one customer alone. A contract rule that fits a purchase and is in date beats everything on the customer's price list.","parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"},"startsAt":{"description":"When the price starts to count. Unset, already","type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"endsAt":{"description":"When it stops counting. Unset, never","type":"string","format":"date-time","examples":["2027-10-07T00:00:00.000Z"]}},"required":["id","product","kind","value"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"put":{"operationId":"replaceContractRules","summary":"Replace contract prices","tags":["Pricing"],"description":"Replaces the whole set; send an empty list to clear it. Rules have the same shape as price list rules, with optional dates. `add` and `fixed` values are in the currency of the customer's list. Two rules for the same items and tier must not be in date at the same time.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"},"startsAt":{"description":"When the price starts to count. Unset, already","type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"endsAt":{"description":"When it stops counting. Unset, never","type":"string","format":"date-time","examples":["2027-10-07T00:00:00.000Z"]}},"required":["product","kind","value"]}}},"required":["rules"]}}}},"parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"description":"Narrows the rule within its product. Unset, the whole product","type":"string","minLength":1,"maxLength":80,"examples":["com"]},"term":{"description":"Narrows a number rule to one rental length","type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"description":"Narrows the rule to first purchases or renewals. Unset, both","type":"string","enum":["new","renew","restore"]},"minQuantity":{"examples":[10],"description":"A volume tier: the rule only fits when at least this many are bought together (years, seats, numbers in one order). Of rules aimed at the same thing, the highest tier reached wins","type":"integer","minimum":2,"maximum":100000},"kind":{"type":"string","enum":["markup","add","fixed"],"description":"`markup` adds a share of wholesale; `add` adds a fixed amount; `fixed` is the price itself"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Basis points for `markup` (2500 is 25%); minor units of the list's currency for `add` and `fixed`"},"startsAt":{"description":"When the price starts to count. Unset, already","type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"endsAt":{"description":"When it stops counting. Unset, never","type":"string","format":"date-time","examples":["2027-10-07T00:00:00.000Z"]}},"required":["id","product","kind","value"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, or `invalid_dates`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, or `invalid_dates`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/price-lists/quote":{"post":{"operationId":"quotePrices","summary":"Quote customer prices","tags":["Pricing"],"description":"Works out what a customer, or anyone on a list, pays for items at the wholesale prices given. Nothing is bought. With neither a customer nor a list, the default list. A customer's contract prices count; prices fixed on single items do not, since no item is named.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"priceListId":{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"match":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},"term":{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},"action":{"default":"new","type":"string","enum":["new","renew","restore"],"description":"`new` is a first purchase; `renew` is a renewal or an extension; `restore` is bringing a domain back out of the registry's redemption period, which costs many times a renewal"},"quantity":{"default":1,"description":"How many are bought together, for volume tiers","type":"integer","minimum":1,"maximum":100000,"examples":[1]},"cost":{"type":"integer","minimum":0,"examples":[1440],"description":"The wholesale price of one unit, in US cents"}},"required":["product","cost"]}}},"required":["items"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The list the prices came from"},"data":{"type":"array","items":{"type":"object","properties":{"cost":{"type":"integer","minimum":0,"examples":[1440],"description":"The wholesale price of one unit, in US cents"},"price":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer pays for one unit, in `currency`"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"ISO 4217 currency code. A price list takes USD, EUR, GBP, CAD, AUD, NZD, CHF, SEK, NOK, DKK, PLN, INR, SGD, HKD, AED, ZAR, BRL or MXN: currencies counted in hundredths"},"priceUsd":{"type":"integer","minimum":0,"examples":[1440],"description":"`price` in US cents at the list's rate"},"ruleId":{"anyOf":[{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The rule that set the price, if one did"},"level":{"type":"string","enum":["override","contract","list","none"],"description":"What set the price: the item's own price (`override`), the customer's contract, their price list, or `none` when you have no list and the customer pays wholesale"},"floored":{"type":"boolean","description":"True when the price was raised to wholesale"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored"],"additionalProperties":false}}},"required":["priceListId","data"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/sales":{"get":{"operationId":"listSales","summary":"List sales","tags":["Pricing"],"description":"Every purchase and renewal made for a customer, newest first, with what it cost you and what the customer pays at the prices in force at the time.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false},{"schema":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"in":"query","name":"product","required":false},{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"priceListId","required":false,"description":"Only sales priced from this list"},{"schema":{"type":"string","enum":["override","contract","list","none"]},"in":"query","name":"level","required":false,"description":"What set the price: the item's own price (`override`), the customer's contract, their price list, or `none` when you have no list and the customer pays wholesale"},{"schema":{"type":"string","format":"date-time"},"example":"2026-10-07T11:04:31.000Z","in":"query","name":"from","required":false,"description":"Only sales made at or after this moment"},{"schema":{"type":"string","format":"date-time"},"example":"2026-11-01T00:00:00.000Z","in":"query","name":"to","required":false,"description":"Only sales made before this moment"},{"schema":{"type":"string"},"in":"query","name":"invoiced","required":false,"description":"`false` for sales not on an invoice yet, `true` for those that are"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"action":{"type":"string","enum":["new","renew","restore"],"description":"`new` is a first purchase; `renew` is a renewal or an extension; `restore` is bringing a domain back out of the registry's redemption period, which costs many times a renewal"},"reference":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false,"description":"What was bought"},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"term":{"anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}],"description":"The rental length sold, for a number. Null for anything else"},"quantity":{"type":"integer","examples":[2],"description":"Units sold. Under zero on a credit, as are `cost`, `price` and `priceUsd`"},"unitCost":{"type":"integer","minimum":0,"examples":[1440],"description":"Wholesale price of one unit, in US cents"},"cost":{"type":"integer","examples":[1440],"description":"What you were charged, in US cents"},"unitPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer pays for one unit, in `currency`"},"price":{"type":"integer","examples":[1440],"description":"What the customer pays, in `currency`"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency the customer is charged in"},"rate":{"type":"integer","examples":[1000000],"description":"The rate the sale was made at"},"priceUsd":{"type":"integer","examples":[1440],"description":"`price` in US cents at that rate. Profit is this less `cost`"},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"ruleId":{"anyOf":[{"type":"string","examples":["prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The rule that set the price, if one did"},"level":{"type":"string","enum":["override","contract","list","none"],"description":"What set the price: the item's own price (`override`), the customer's contract, their price list, or `none` when you have no list and the customer pays wholesale"},"floored":{"type":"boolean","description":"True when the price was raised to wholesale because it would have sat under it"},"creditOf":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"On a credit, the sale it hands back: one that was cancelled and refunded after its invoice was paid. Null on an ordinary sale"},"invoiceId":{"anyOf":[{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The invoice this sale is billed on. Null until it is invoiced"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","customerId","product","action","reference","description","term","quantity","unitCost","cost","unitPrice","price","currency","rate","priceUsd","priceListId","ruleId","level","floored","creditOf","invoiceId","createdAt"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/sales/summary":{"get":{"operationId":"summariseSales","summary":"Summarise sales","tags":["Pricing"],"description":"Totals for the sales the filters cover: one customer, one product, one list, a stretch of time, or everything. With `groupBy`, the same totals split one way as well. Always in US cents, whatever currency each sale was charged in.","parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false},{"schema":{"type":"string","enum":["number","domain","domain_privacy","licence"]},"in":"query","name":"product","required":false},{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"priceListId","required":false,"description":"Only sales priced from this list"},{"schema":{"type":"string","enum":["override","contract","list","none"]},"in":"query","name":"level","required":false,"description":"What set the price: the item's own price (`override`), the customer's contract, their price list, or `none` when you have no list and the customer pays wholesale"},{"schema":{"type":"string","format":"date-time"},"example":"2026-10-07T11:04:31.000Z","in":"query","name":"from","required":false,"description":"Only sales made at or after this moment"},{"schema":{"type":"string","format":"date-time"},"example":"2026-11-01T00:00:00.000Z","in":"query","name":"to","required":false,"description":"Only sales made before this moment"},{"schema":{"type":"string","enum":["product","customer","priceList","level","month"]},"in":"query","name":"groupBy","required":false,"description":"Splits the totals. `month` is the calendar month in UTC, as `2026-10`"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"count":{"type":"integer","examples":[12]},"cost":{"type":"integer","examples":[1440],"description":"What you were charged"},"price":{"type":"integer","examples":[1440],"description":"What your customers pay, in US cents at the rate of each sale"},"profit":{"type":"integer","examples":[2400],"description":"`price` less `cost`"},"marginBps":{"type":"integer","examples":[1667],"description":"Profit as a share of `price`, in basis points"},"groups":{"description":"One row for each value of `groupBy`. Absent without it","type":"array","items":{"type":"object","properties":{"key":{"examples":["domain"],"description":"The product, customer id, price list id, level or month. Null for sales made with no price list, when grouping by list","type":["string","null"]},"count":{"type":"integer","examples":[12]},"cost":{"type":"integer","examples":[1440],"description":"What you were charged"},"price":{"type":"integer","examples":[1440],"description":"What your customers pay, in US cents at the rate of each sale"},"profit":{"type":"integer","examples":[2400],"description":"`price` less `cost`"},"marginBps":{"type":"integer","examples":[1667],"description":"Profit as a share of `price`, in basis points"}},"required":["key","count","cost","price","profit","marginBps"],"additionalProperties":false}}},"required":["count","cost","price","profit","marginBps"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/invoices":{"post":{"operationId":"createInvoice","summary":"Create an invoice","tags":["Invoices"],"description":"Bills a customer for sales not yet on an invoice: every one of them, or the ones you name. Each line is a copy of a sale at the price it was made at. An invoice is in one currency and holds at most 500 sales, oldest first. ResellerHQ does not collect payment from your customers: you take the money however you already do, and record it here. Send an Idempotency-Key header so a retry can never invoice twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"dueInDays":{"examples":[14],"description":"How many days from now the invoice is due. Unset, your account's default, or 14 days if it has none","type":"integer","minimum":0,"maximum":365},"taxBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"note":{"description":"Shown on the invoice. Unset, your account's default note; `null` for no note","anyOf":[{"type":"string","minLength":1,"maxLength":1000},{"type":"null"}]},"saleIds":{"description":"Bill only these sales. Unset, everything not yet invoiced","minItems":1,"maxItems":500,"type":"array","items":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]}},"currency":{"description":"Bill only the sales in this currency, for a customer with sales in more than one","type":"string","pattern":"^[A-Z]{3}$","examples":["USD"]}},"required":["customerId"]}}}},"parameters":[{"schema":{"type":"string","minLength":8,"maxLength":200},"example":"2f1c9a52-7d0e-4a8e-9a53-0c1f6f3f2b11","in":"header","name":"Idempotency-Key","required":false,"description":"A value unique to this request, such as a UUID. A retry with the same key within 24 hours returns the first outcome instead of running again."}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["INV-0001"],"description":"Counts up from INV-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2],"description":"Under zero on a credit for a sale handed back"},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["saleId","description","quantity","unitPrice","total"],"additionalProperties":false}},"subtotal":{"type":"integer","minimum":0,"examples":[2878],"description":"The lines added up, before tax"},"taxBps":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},{"type":"null"}],"description":"The tax rate in basis points. Null when there is no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"`subtotal` times the tax rate, rounded"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void"],"description":"`open` is waiting to be paid; `paid` is your record that it was; `void` was withdrawn"},"overdue":{"type":"boolean","description":"True for an open invoice whose due date has passed: from a day after `dueAt`, so an invoice due today is not overdue today"},"shared":{"type":"boolean","description":"True once `POST /invoices/{id}/share` has made a public link for this invoice, false again once revoked. The token itself is never in this response or the list"},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"dueAt":{"type":"string","format":"date-time","examples":["2026-10-21T11:04:31.000Z"]},"paidAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"voidedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"note":{"examples":["Thank you for your business"],"type":["string","null"]},"issuer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Northwind Telecom"]},"legalName":{"examples":[null],"type":["string","null"]},"addressLines":{"type":"array","items":{"type":"string"},"examples":[[]]},"taxId":{"examples":[null],"type":["string","null"]},"billingEmail":{"examples":[null],"type":["string","null"]}},"required":["name","legalName","addressLines","taxId","billingEmail"],"additionalProperties":false},{"type":"null"}],"description":"Your account as it billed this invoice, copied at the time it was issued. Null on invoices made before you set any billing details"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","issuer"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error` or `invalid_idempotency_key`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `idempotency_in_progress`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"idempotency_in_progress","message":"A request with this key is still being processed","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `nothing_to_invoice`, `mixed_currencies`, `sale_unavailable`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `nothing_to_invoice`, `mixed_currencies`, `sale_unavailable`, or `idempotency_key_reused`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"nothing_to_invoice","message":"This customer has no sales waiting to be invoiced","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"get":{"operationId":"listInvoices","summary":"List invoices","tags":["Invoices"],"description":"Newest first.","parameters":[{"schema":{"default":25,"type":"integer","minimum":1,"maximum":100},"in":"query","name":"limit","required":false,"description":"How many to return"},{"schema":{"type":"string"},"in":"query","name":"cursor","required":false,"description":"`nextCursor` from the previous page"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false},{"schema":{"type":"string","enum":["open","paid","void"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"q","required":false,"description":"Text to look for in the invoice number, or in the customer's name or email"},{"schema":{"type":"string"},"in":"query","name":"overdue","required":false,"description":"`true` for open invoices whose due date has passed, `false` for the rest"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["INV-0001"],"description":"Counts up from INV-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2],"description":"Under zero on a credit for a sale handed back"},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["saleId","description","quantity","unitPrice","total"],"additionalProperties":false}},"subtotal":{"type":"integer","minimum":0,"examples":[2878],"description":"The lines added up, before tax"},"taxBps":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},{"type":"null"}],"description":"The tax rate in basis points. Null when there is no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"`subtotal` times the tax rate, rounded"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void"],"description":"`open` is waiting to be paid; `paid` is your record that it was; `void` was withdrawn"},"overdue":{"type":"boolean","description":"True for an open invoice whose due date has passed: from a day after `dueAt`, so an invoice due today is not overdue today"},"shared":{"type":"boolean","description":"True once `POST /invoices/{id}/share` has made a public link for this invoice, false again once revoked. The token itself is never in this response or the list"},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"dueAt":{"type":"string","format":"date-time","examples":["2026-10-21T11:04:31.000Z"]},"paidAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"voidedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"note":{"examples":["Thank you for your business"],"type":["string","null"]},"issuer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Northwind Telecom"]},"legalName":{"examples":[null],"type":["string","null"]},"addressLines":{"type":"array","items":{"type":"string"},"examples":[[]]},"taxId":{"examples":[null],"type":["string","null"]},"billingEmail":{"examples":[null],"type":["string","null"]}},"required":["name","legalName","addressLines","taxId","billingEmail"],"additionalProperties":false},{"type":"null"}],"description":"Your account as it billed this invoice, copied at the time it was issued. Null on invoices made before you set any billing details"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","issuer"],"additionalProperties":false}},"nextCursor":{"examples":[null],"description":"Pass as `cursor` for the next page. `null` on the last page","type":["string","null"]},"total":{"type":"integer","minimum":0,"examples":[1],"description":"How many match across every page"}},"required":["data","nextCursor","total"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/invoices/summary":{"get":{"operationId":"summariseInvoices","summary":"Summarise invoices","tags":["Invoices"],"description":"What the business is owed, one row for each currency you have invoiced in, sorted by currency code. `open` is every invoice still open, overdue ones included; `overdue` is the part of it past its due date. Void invoices are not counted. An account that has never invoiced gets no rows.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"ISO 4217 currency code"},"open":{"type":"integer","minimum":0,"examples":[2878],"description":"On invoices waiting to be paid, overdue ones included"},"overdue":{"type":"integer","minimum":0,"examples":[0],"description":"The part of `open` past its due date"},"paid":{"type":"integer","minimum":0,"examples":[2878],"description":"On invoices you marked paid"},"openCount":{"type":"integer","minimum":0,"examples":[2],"description":"How many invoices make up `open`"},"overdueCount":{"type":"integer","minimum":0,"examples":[0],"description":"How many invoices make up `overdue`"},"paidCount":{"type":"integer","minimum":0,"examples":[1],"description":"How many invoices make up `paid`"}},"required":["currency","open","overdue","paid","openCount","overdueCount","paidCount"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/invoices/{id}":{"get":{"operationId":"getInvoice","summary":"Get an invoice","tags":["Invoices"],"parameters":[{"schema":{"type":"string"},"example":"inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["INV-0001"],"description":"Counts up from INV-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2],"description":"Under zero on a credit for a sale handed back"},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["saleId","description","quantity","unitPrice","total"],"additionalProperties":false}},"subtotal":{"type":"integer","minimum":0,"examples":[2878],"description":"The lines added up, before tax"},"taxBps":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},{"type":"null"}],"description":"The tax rate in basis points. Null when there is no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"`subtotal` times the tax rate, rounded"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void"],"description":"`open` is waiting to be paid; `paid` is your record that it was; `void` was withdrawn"},"overdue":{"type":"boolean","description":"True for an open invoice whose due date has passed: from a day after `dueAt`, so an invoice due today is not overdue today"},"shared":{"type":"boolean","description":"True once `POST /invoices/{id}/share` has made a public link for this invoice, false again once revoked. The token itself is never in this response or the list"},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"dueAt":{"type":"string","format":"date-time","examples":["2026-10-21T11:04:31.000Z"]},"paidAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"voidedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"note":{"examples":["Thank you for your business"],"type":["string","null"]},"issuer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Northwind Telecom"]},"legalName":{"examples":[null],"type":["string","null"]},"addressLines":{"type":"array","items":{"type":"string"},"examples":[[]]},"taxId":{"examples":[null],"type":["string","null"]},"billingEmail":{"examples":[null],"type":["string","null"]}},"required":["name","legalName","addressLines","taxId","billingEmail"],"additionalProperties":false},{"type":"null"}],"description":"Your account as it billed this invoice, copied at the time it was issued. Null on invoices made before you set any billing details"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","issuer"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/invoices/{id}/pay":{"post":{"operationId":"payInvoice","summary":"Mark an invoice paid","tags":["Invoices"],"description":"Records that the customer paid. Nothing is charged. ResellerHQ does not collect payment from your customers: you take the money however you already do, and record it here.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"paidAt":{"description":"When the money arrived. Unset, now","type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}}},{"type":"null"}]}}}},"parameters":[{"schema":{"type":"string"},"example":"inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["INV-0001"],"description":"Counts up from INV-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2],"description":"Under zero on a credit for a sale handed back"},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["saleId","description","quantity","unitPrice","total"],"additionalProperties":false}},"subtotal":{"type":"integer","minimum":0,"examples":[2878],"description":"The lines added up, before tax"},"taxBps":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},{"type":"null"}],"description":"The tax rate in basis points. Null when there is no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"`subtotal` times the tax rate, rounded"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void"],"description":"`open` is waiting to be paid; `paid` is your record that it was; `void` was withdrawn"},"overdue":{"type":"boolean","description":"True for an open invoice whose due date has passed: from a day after `dueAt`, so an invoice due today is not overdue today"},"shared":{"type":"boolean","description":"True once `POST /invoices/{id}/share` has made a public link for this invoice, false again once revoked. The token itself is never in this response or the list"},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"dueAt":{"type":"string","format":"date-time","examples":["2026-10-21T11:04:31.000Z"]},"paidAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"voidedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"note":{"examples":["Thank you for your business"],"type":["string","null"]},"issuer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Northwind Telecom"]},"legalName":{"examples":[null],"type":["string","null"]},"addressLines":{"type":"array","items":{"type":"string"},"examples":[[]]},"taxId":{"examples":[null],"type":["string","null"]},"billingEmail":{"examples":[null],"type":["string","null"]}},"required":["name","legalName","addressLines","taxId","billingEmail"],"additionalProperties":false},{"type":"null"}],"description":"Your account as it billed this invoice, copied at the time it was issued. Null on invoices made before you set any billing details"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","issuer"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `invoice_not_open`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `invoice_not_open`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"invoice_not_open","message":"This invoice is already paid","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_paid_at`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_paid_at`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"invalid_paid_at","message":"An invoice cannot be paid in the future","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/invoices/{id}/void":{"post":{"operationId":"voidInvoice","summary":"Void an invoice","tags":["Invoices"],"description":"Withdraws an open invoice. Its number is not used again, and its sales can go on another invoice. A paid invoice cannot be voided.","parameters":[{"schema":{"type":"string"},"example":"inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["INV-0001"],"description":"Counts up from INV-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2],"description":"Under zero on a credit for a sale handed back"},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["saleId","description","quantity","unitPrice","total"],"additionalProperties":false}},"subtotal":{"type":"integer","minimum":0,"examples":[2878],"description":"The lines added up, before tax"},"taxBps":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},{"type":"null"}],"description":"The tax rate in basis points. Null when there is no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"`subtotal` times the tax rate, rounded"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void"],"description":"`open` is waiting to be paid; `paid` is your record that it was; `void` was withdrawn"},"overdue":{"type":"boolean","description":"True for an open invoice whose due date has passed: from a day after `dueAt`, so an invoice due today is not overdue today"},"shared":{"type":"boolean","description":"True once `POST /invoices/{id}/share` has made a public link for this invoice, false again once revoked. The token itself is never in this response or the list"},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"dueAt":{"type":"string","format":"date-time","examples":["2026-10-21T11:04:31.000Z"]},"paidAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"voidedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[null]},"note":{"examples":["Thank you for your business"],"type":["string","null"]},"issuer":{"anyOf":[{"type":"object","properties":{"name":{"type":"string","examples":["Northwind Telecom"]},"legalName":{"examples":[null],"type":["string","null"]},"addressLines":{"type":"array","items":{"type":"string"},"examples":[[]]},"taxId":{"examples":[null],"type":["string","null"]},"billingEmail":{"examples":[null],"type":["string","null"]}},"required":["name","legalName","addressLines","taxId","billingEmail"],"additionalProperties":false},{"type":"null"}],"description":"Your account as it billed this invoice, copied at the time it was issued. Null on invoices made before you set any billing details"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","issuer"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `invoice_not_open`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `invoice_not_open`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"invoice_not_open","message":"This invoice is already paid","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/invoices/{id}/share":{"post":{"operationId":"shareInvoice","summary":"Share an invoice","tags":["Invoices"],"description":"Creates a public, read-only link to this invoice that needs no API key: `GET /public/invoices/{token}`. Calling this again returns the same token, so the share button is safe to press twice. Works on an invoice in any status.","parameters":[{"schema":{"type":"string"},"example":"inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"The token is the same one already shared, if there was one","content":{"application/json":{"schema":{"description":"The token is the same one already shared, if there was one","type":"object","properties":{"token":{"type":"string","examples":["kq3F2n8y9mQe...base64url..."],"description":"Put at the end of `/public/invoices/{token}`. Unguessable; treat it like a capability on this one invoice, not a secret you otherwise protect"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["token","createdAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"delete":{"operationId":"revokeInvoiceShare","summary":"Revoke an invoice link","tags":["Invoices"],"description":"The public link stops working at once. An invoice with no link also answers 204: there is nothing to revoke. Sharing again afterwards mints a different token; the old one stays dead for good.","parameters":[{"schema":{"type":"string"},"example":"inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"204":{"description":"Revoked, or there was nothing to revoke"},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/customers/{id}/balance":{"get":{"operationId":"getCustomerBalance","summary":"Get a customer's balance","tags":["Invoices"],"description":"What a customer owes you and has paid, with one row for each currency they have been sold in. A customer with no sales has no rows.","parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"ISO 4217 currency code"},"uninvoiced":{"type":"integer","examples":[2878],"description":"Sold but not on an invoice yet, before any tax. Under zero when the customer is owed a credit"},"open":{"type":"integer","minimum":0,"examples":[2878],"description":"On invoices waiting to be paid, overdue ones included"},"overdue":{"type":"integer","minimum":0,"examples":[0],"description":"The part of `open` past its due date"},"paid":{"type":"integer","minimum":0,"examples":[2878],"description":"On invoices you marked paid"}},"required":["currency","uninvoiced","open","overdue","paid"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/billing-runs":{"post":{"operationId":"previewBillingRun","summary":"Preview a billing run","tags":["Invoices"],"description":"Computes, but does not create, one invoice per `(customerId, currency)` pair that has eligible, uninvoiced sales made at or before `asOf`: the same rules `POST /invoices` already enforces, applied to every customer at once, at most 500 sales per row, oldest first. Nothing is written to your sales or invoices; nothing bills a customer until a run is committed. One run holds at most 1000 rows: with more customers waiting than that, `truncated` is true and the rest come up in your next run.","requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"asOf":{"description":"The cut-off: only sales made at or before this count. Unset, now","type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}}},{"type":"null"}]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"asOf":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"The cut-off this run fixed: only sales made at or before it count"},"status":{"type":"string","enum":["previewed","committing","completed","completed_with_failures"],"description":"`previewed` is waiting to be committed. `committing` is being billed by the worker. `completed` billed every row. `completed_with_failures` billed what it could; commit it again to retry the rows that failed"},"rows":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on this row"},"saleIds":{"type":"array","items":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":"The sales this row would bill, oldest first, as of the run"},"subtotal":{"type":"integer","examples":[2878],"description":"The eligible sales added up, before tax"},"tax":{"type":"integer","examples":[2878],"description":"`subtotal` times your account's default tax rate, rounded. Zero on a skipped row: no invoice would be raised, so there is nothing to tax"},"total":{"type":"integer","examples":[2878],"description":"`subtotal` plus `tax`. Equal to `subtotal` on a skipped row"},"status":{"type":"string","enum":["pending","skipped","excluded","done","failed"],"description":"`pending` would be billed on commit. `skipped` has nothing to bill, see `reason`. `excluded` is held back by hand. `done` was billed, see `invoiceId`. `failed` could not be billed when commit tried it, see `reason`; committing this run again retries only the rows still `failed`"},"reason":{"description":"Why a `skipped` or `failed` row did not bill. Null otherwise","type":["string","null"]},"invoiceId":{"anyOf":[{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The invoice a `done` row billed. Null otherwise"}},"required":["customerId","currency","saleIds","subtotal","tax","total","status","reason","invoiceId"],"additionalProperties":false},"description":"One row per `(customerId, currency)` pair with eligible, uninvoiced sales"},"truncated":{"type":"boolean","description":"True when you had more customers waiting than the 1000 rows one run holds: this run covers the lowest customer ids, and the rest come up in your next run once these are invoiced"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","asOf","status","rows","truncated","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/billing-runs/{id}":{"get":{"operationId":"getBillingRun","summary":"Get a billing run","tags":["Invoices"],"parameters":[{"schema":{"type":"string"},"example":"brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"asOf":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"The cut-off this run fixed: only sales made at or before it count"},"status":{"type":"string","enum":["previewed","committing","completed","completed_with_failures"],"description":"`previewed` is waiting to be committed. `committing` is being billed by the worker. `completed` billed every row. `completed_with_failures` billed what it could; commit it again to retry the rows that failed"},"rows":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on this row"},"saleIds":{"type":"array","items":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":"The sales this row would bill, oldest first, as of the run"},"subtotal":{"type":"integer","examples":[2878],"description":"The eligible sales added up, before tax"},"tax":{"type":"integer","examples":[2878],"description":"`subtotal` times your account's default tax rate, rounded. Zero on a skipped row: no invoice would be raised, so there is nothing to tax"},"total":{"type":"integer","examples":[2878],"description":"`subtotal` plus `tax`. Equal to `subtotal` on a skipped row"},"status":{"type":"string","enum":["pending","skipped","excluded","done","failed"],"description":"`pending` would be billed on commit. `skipped` has nothing to bill, see `reason`. `excluded` is held back by hand. `done` was billed, see `invoiceId`. `failed` could not be billed when commit tried it, see `reason`; committing this run again retries only the rows still `failed`"},"reason":{"description":"Why a `skipped` or `failed` row did not bill. Null otherwise","type":["string","null"]},"invoiceId":{"anyOf":[{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The invoice a `done` row billed. Null otherwise"}},"required":["customerId","currency","saleIds","subtotal","tax","total","status","reason","invoiceId"],"additionalProperties":false},"description":"One row per `(customerId, currency)` pair with eligible, uninvoiced sales"},"truncated":{"type":"boolean","description":"True when you had more customers waiting than the 1000 rows one run holds: this run covers the lowest customer ids, and the rest come up in your next run once these are invoiced"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","asOf","status","rows","truncated","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/billing-runs/{id}/commit":{"post":{"operationId":"commitBillingRun","summary":"Commit a billing run","tags":["Invoices"],"description":"Starts billing every `pending` row of a `previewed` run: raises the invoices, one per row, with the exact sales the preview fixed. Returns as soon as the run moves to `committing`; a background worker finishes it, so poll `GET /billing-runs/{id}` for progress. Calling this again on a `completed_with_failures` run retries only the rows still `failed`, leaving every `done`, `skipped` and `excluded` row untouched, so it is always safe to repeat.","parameters":[{"schema":{"type":"string"},"example":"brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"asOf":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"The cut-off this run fixed: only sales made at or before it count"},"status":{"type":"string","enum":["previewed","committing","completed","completed_with_failures"],"description":"`previewed` is waiting to be committed. `committing` is being billed by the worker. `completed` billed every row. `completed_with_failures` billed what it could; commit it again to retry the rows that failed"},"rows":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on this row"},"saleIds":{"type":"array","items":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":"The sales this row would bill, oldest first, as of the run"},"subtotal":{"type":"integer","examples":[2878],"description":"The eligible sales added up, before tax"},"tax":{"type":"integer","examples":[2878],"description":"`subtotal` times your account's default tax rate, rounded. Zero on a skipped row: no invoice would be raised, so there is nothing to tax"},"total":{"type":"integer","examples":[2878],"description":"`subtotal` plus `tax`. Equal to `subtotal` on a skipped row"},"status":{"type":"string","enum":["pending","skipped","excluded","done","failed"],"description":"`pending` would be billed on commit. `skipped` has nothing to bill, see `reason`. `excluded` is held back by hand. `done` was billed, see `invoiceId`. `failed` could not be billed when commit tried it, see `reason`; committing this run again retries only the rows still `failed`"},"reason":{"description":"Why a `skipped` or `failed` row did not bill. Null otherwise","type":["string","null"]},"invoiceId":{"anyOf":[{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The invoice a `done` row billed. Null otherwise"}},"required":["customerId","currency","saleIds","subtotal","tax","total","status","reason","invoiceId"],"additionalProperties":false},"description":"One row per `(customerId, currency)` pair with eligible, uninvoiced sales"},"truncated":{"type":"boolean","description":"True when you had more customers waiting than the 1000 rows one run holds: this run covers the lowest customer ids, and the rest come up in your next run once these are invoiced"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","asOf","status","rows","truncated","createdAt","updatedAt"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/billing-runs/{id}/exclude":{"post":{"operationId":"excludeFromBillingRun","summary":"Exclude a row from a billing run","tags":["Invoices"],"description":"Holds one `(customerId, currency)` row back from this run, so it is not billed on commit: this only works on a `previewed` run, and repeating it on a row already `excluded` is a no-op.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"The customer of the row to exclude"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of the row to exclude"}},"required":["customerId","currency"]}}}},"parameters":[{"schema":{"type":"string"},"example":"brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["brn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"asOf":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"The cut-off this run fixed: only sales made at or before it count"},"status":{"type":"string","enum":["previewed","committing","completed","completed_with_failures"],"description":"`previewed` is waiting to be committed. `committing` is being billed by the worker. `completed` billed every row. `completed_with_failures` billed what it could; commit it again to retry the rows that failed"},"rows":{"type":"array","items":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","examples":["USD"],"description":"The currency of every amount on this row"},"saleIds":{"type":"array","items":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"description":"The sales this row would bill, oldest first, as of the run"},"subtotal":{"type":"integer","examples":[2878],"description":"The eligible sales added up, before tax"},"tax":{"type":"integer","examples":[2878],"description":"`subtotal` times your account's default tax rate, rounded. Zero on a skipped row: no invoice would be raised, so there is nothing to tax"},"total":{"type":"integer","examples":[2878],"description":"`subtotal` plus `tax`. Equal to `subtotal` on a skipped row"},"status":{"type":"string","enum":["pending","skipped","excluded","done","failed"],"description":"`pending` would be billed on commit. `skipped` has nothing to bill, see `reason`. `excluded` is held back by hand. `done` was billed, see `invoiceId`. `failed` could not be billed when commit tried it, see `reason`; committing this run again retries only the rows still `failed`"},"reason":{"description":"Why a `skipped` or `failed` row did not bill. Null otherwise","type":["string","null"]},"invoiceId":{"anyOf":[{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The invoice a `done` row billed. Null otherwise"}},"required":["customerId","currency","saleIds","subtotal","tax","total","status","reason","invoiceId"],"additionalProperties":false},"description":"One row per `(customerId, currency)` pair with eligible, uninvoiced sales"},"truncated":{"type":"boolean","description":"True when you had more customers waiting than the 1000 rows one run holds: this run covers the lowest customer ids, and the rest come up in your next run once these are invoiced"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"updatedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","asOf","status","rows","truncated","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `run_not_previewed` or `row_not_pending`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `run_not_previewed` or `row_not_pending`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"run_not_previewed","message":"Only a run still being previewed can be changed","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/webhook-endpoints":{"post":{"operationId":"createWebhookEndpoint","summary":"Create an endpoint","tags":["Webhooks"],"description":"Deliveries are signed per the Standard Webhooks specification. The signing secret is returned once, in this response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri","examples":["https://example.com/hooks/resellerhq"],"description":"Must be `https` and resolve to a public address"},"events":{"default":["*"],"examples":[["number.message.received"]],"description":"The event types to deliver; `*` is every event","minItems":1,"type":"array","items":{"anyOf":[{"type":"string","enum":["*"]},{"type":"string","enum":["number.order.completed","number.order.failed","number.rental.created","number.rental.renewed","number.rental.renewal_failed","number.rental.cancelled","number.rental.expired","number.message.received","domain.registered","domain.renewed","domain.renewal_pending","domain.registration_failed","domain.renewal_failed","domain.needs_attention","domain.expired","domain.updated","domain.auth_code_generated","domain.transferred_out","domain.restored","domain.restore_failed","domain.deleted","domain.suspended","domain.unsuspended","licence.created","licence.updated","licence.renewed","licence.renewal_failed","licence.cancelled","price_list.updated","sale.below_cost","invoice.created","invoice.paid","invoice.voided"]}]}}},"required":["url"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["whe_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"url":{"type":"string","examples":["https://example.com/hooks/resellerhq"]},"events":{"type":"array","items":{"type":"string"},"examples":[["number.message.received"]],"description":"The event types delivered here; `*` is every event"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"secret":{"type":"string","examples":["whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"],"description":"The signing secret. Store it now; it is not shown again"}},"required":["id","url","events","enabled","createdAt","secret"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `invalid_webhook_url` or `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `invalid_webhook_url` or `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"invalid_webhook_url","message":"Webhook URL must use https and resolve to a public address","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_endpoints`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_endpoints`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"too_many_endpoints","message":"At most 10 webhook endpoints","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"get":{"operationId":"listWebhookEndpoints","summary":"List endpoints","tags":["Webhooks"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["whe_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"url":{"type":"string","examples":["https://example.com/hooks/resellerhq"]},"events":{"type":"array","items":{"type":"string"},"examples":[["number.message.received"]],"description":"The event types delivered here; `*` is every event"},"enabled":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","url","events","enabled","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/webhook-endpoints/{id}":{"delete":{"operationId":"deleteWebhookEndpoint","summary":"Delete an endpoint","tags":["Webhooks"],"description":"Deliveries to it stop at once.","parameters":[{"schema":{"type":"string"},"example":"whe_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"204":{"description":"Removed"},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/api-keys":{"get":{"operationId":"listApiKeys","summary":"List API keys","tags":["Keys"],"description":"The active keys on this side of the account. The keys themselves are never returned.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["key_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["production"]},"prefix":{"type":"string","examples":["rhq_test_k3J9xQ"],"description":"The first characters of the key, to recognise it by"},"lastUsedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","prefix","lastUsedAt","createdAt"],"additionalProperties":false}}},"required":["data"],"additionalProperties":false}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}},"post":{"operationId":"createApiKey","summary":"Create an API key","tags":["Keys"],"description":"The key itself is returned once, in this response, and cannot be read again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":60,"examples":["production"]}},"required":["name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["key_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["production"]},"prefix":{"type":"string","examples":["rhq_test_k3J9xQ"],"description":"The first characters of the key, to recognise it by"},"lastUsedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"key":{"type":"string","examples":["rhq_test_k3J9xQ2mVb7TnY4wLc8HdR5sZ"],"description":"The key itself. Store it now; it is not shown again"}},"required":["id","name","prefix","lastUsedAt","createdAt","key"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `validation_error`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `validation_error`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}}}},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_keys`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_keys`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"too_many_keys","message":"At most 20 active API keys","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}},"/v1/api-keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key","tags":["Keys"],"description":"The key stops working at once. This cannot be undone.","parameters":[{"schema":{"type":"string"},"example":"key_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"204":{"description":"Revoked"},"401":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","content":{"application/json":{"schema":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"rate_limited","message":"Rate limit exceeded, retry in 1 minute","requestId":"req-4f"}}}}}}}},"servers":[{"url":"https://163-123-236-68.sslip.io/api"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account","description":"The account an API key belongs to."},{"name":"Wallet","description":"The prepaid balance and its history."},{"name":"Customers","description":"The people you sell to."},{"name":"Numbers","description":"Phone numbers that receive SMS."},{"name":"Domains","description":"Domain search, registration and renewal."},{"name":"Mailbox licences","description":"Google Workspace and Microsoft 365 seats."},{"name":"Pricing","description":"What you charge your customers, and what you have sold them."},{"name":"Invoices","description":"Bills to your customers for what you sold them, and what they owe."},{"name":"Orders","description":"Everything bought, across products."},{"name":"Webhooks","description":"Endpoints that receive signed events."},{"name":"Keys","description":"API keys for calling this API."}]}