{"openapi":"3.1.0","info":{"title":"ResellerHQ API","version":"2026-10-07","description":"Buy and manage phone numbers, domains and Google mailboxes 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\"`"},"isSubReseller":{"type":"boolean","description":"Whether this account is itself a sub-reseller, invited by another"},"hasSubResellers":{"type":"boolean","description":"Whether this account has a sub-reseller of its own, or an invitation out to one"},"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"},"productRequests":{"type":"object","properties":{"numbers":{"format":"date-time","examples":[null],"type":["string","null"]},"domains":{"format":"date-time","examples":[null],"type":["string","null"]},"licences":{"format":"date-time","examples":[null],"type":["string","null"]}},"required":["numbers","domains","licences"],"additionalProperties":false,"description":"When this account asked for each product line to be switched on, or null if it never has"},"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},"walletTopUps":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether `POST /wallet/top-ups` can open a Stripe Checkout session: a live account with `STRIPE_SECRET_KEY` configured on this deployment, and card top-ups may not be offered to every account on this deployment"},"min":{"type":"integer","examples":[500],"description":"Smallest top-up, in cents"},"max":{"type":"integer","examples":[500000],"description":"Largest top-up, in cents"}},"required":["enabled","min","max"],"additionalProperties":false,"description":"Card top-ups through Stripe (issue #335). Sandbox accounts never reach Stripe"},"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"},"address":{"anyOf":[{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":120,"examples":["1 Market Street"]},"line2":{"examples":["Suite 400"],"type":"string","maxLength":120},"city":{"examples":["San Francisco"],"type":"string","maxLength":80},"postalCode":{"examples":["94105"],"type":"string","maxLength":20}},"required":["line1"],"additionalProperties":false,"description":"The street address as its parts"},{"type":"null"}],"description":"The same address as its parts, when it was saved with them. Null, lines only"},"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"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}],"examples":[null],"description":"Your own home country, for the tax rules engine’s presets (issue #341)"},"region":{"examples":[null],"description":"Your own home state or region, for the Indian preset","type":["string","null"]},"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 last updated these billing details"}},"required":["legalName","addressLines","address","taxId","billingEmail","defaultDueDays","defaultTaxBps","invoiceNote","country","region","actor"],"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"},"autoRenewByDefault":{"type":"boolean","description":"New registrations renew themselves from your wallet. Off until turned on"},"digestEnabled":{"type":"boolean","description":"The weekly email of domains expiring soon or failing to auto-renew. On until turned off"},"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 last updated these domain settings"}},"required":["defaultRegistrant","privacyByDefault","autoRenewByDefault","digestEnabled","actor"],"additionalProperties":false},"portal":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"},"url":{"type":"string","examples":["https://northwind.portal.example"],"description":"Where this side of the account answers to customers. Read-only, and computed from your slug: live and sandbox have their own"},"publishedAt":{"format":"date-time","examples":[null],"description":"When the builder’s draft was last published to this live document. Null means never, through the builder - set only by `POST /account/portal/publish`","type":["string","null"]}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification","url","publishedAt"],"additionalProperties":false,"description":"How your customer portal and storefront look, and what your customers may do there"},"portalDraft":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification"],"additionalProperties":false,"description":"The portal builder’s own draft: what Publish will copy onto your live portal. Edited by `PATCH /account/portal/draft`, and only ever reaches customers once you publish it"},"analytics":{"type":"object","properties":{"replayEnabled":{"type":"boolean","description":"Whether the dashboard may send PostHog session replay for this account - off for every account flagged `internal` in the admin panel, whatever this reseller's own setting is, and otherwise this reseller's own choice. A rejected cookie banner or a deployment with no PostHog key configured sends nothing either way, which this field does not know about"}},"required":["replayEnabled"],"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","wallet.manage","customer.read","customer.manage","order.read","product.read","number.manage","domain.manage","licence.manage","mailbox.manage","mailbox.credentials","pricing.read","pricing.manage","sale.read","invoice.read","invoice.manage","webhook.read","webhook.manage","apikey.read","apikey.manage","sandbox.use","team.read","team.manage","activity.read","audit.read","mcpconnection.read","mcpconnection.manage","subreseller.read","subreseller.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","isSubReseller","hasSubResellers","products","productRequests","wallet","walletTopUps","billing","domains","portal","portalDraft","analytics","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}]},"address":{"description":"The same address as its parts, for a form to open again. Send it with `addressLines`, which is still what invoices print","anyOf":[{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":120,"examples":["1 Market Street"]},"line2":{"examples":["Suite 400"],"type":"string","maxLength":120},"city":{"examples":["San Francisco"],"type":"string","maxLength":80},"postalCode":{"examples":["94105"],"type":"string","maxLength":20}},"required":["line1"],"description":"The street address as its parts"},{"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"}]},"country":{"description":"Your own home country, for the tax rules engine’s presets (issue #341)","anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}]},"region":{"examples":["California"],"description":"Your own home state or region, for the Indian preset","anyOf":[{"type":"string","minLength":1,"maxLength":40},{"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"},"address":{"anyOf":[{"type":"object","properties":{"line1":{"type":"string","minLength":1,"maxLength":120,"examples":["1 Market Street"]},"line2":{"examples":["Suite 400"],"type":"string","maxLength":120},"city":{"examples":["San Francisco"],"type":"string","maxLength":80},"postalCode":{"examples":["94105"],"type":"string","maxLength":20}},"required":["line1"],"additionalProperties":false,"description":"The street address as its parts"},{"type":"null"}],"description":"The same address as its parts, when it was saved with them. Null, lines only"},"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"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}],"examples":[null],"description":"Your own home country, for the tax rules engine’s presets (issue #341)"},"region":{"examples":[null],"description":"Your own home state or region, for the Indian preset","type":["string","null"]},"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 last updated these billing details"}},"required":["legalName","addressLines","address","taxId","billingEmail","defaultDueDays","defaultTaxBps","invoiceNote","country","region","actor"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/portal":{"patch":{"operationId":"updateAccountPortal","summary":"Update the customer portal","tags":["Customer portal"],"description":"How your customer portal and storefront look, and what your customers may do there. Send only what changes; `null` clears a field, putting it back on its default - your account name for `brandName`, your billing email for `supportEmail`, on for `enabled`, off for `selfSignup`, read-only for `allow`. Live and sandbox keep their own, so you can brand your sandbox and look at it first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"description":"Turning this off answers the same 404 as an address no reseller holds","type":["boolean","null"]},"brandName":{"examples":["Northwind"],"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"Must be `https`","anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background. Must be `https`; null, `logoUrl` on both","anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"accentColor":{"examples":["#1d4ed8"],"anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}]},"supportEmail":{"examples":["support@northwind.example"],"anyOf":[{"type":"string","maxLength":254,"format":"email"},{"type":"null"}]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"termsUrl":{"examples":["https://northwind.example/terms"],"description":"Must be `https`","anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"description":"Must be `https`","anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"selfSignup":{"description":"Whether a storefront visitor may open an account unasked","type":["boolean","null"]},"allow":{"examples":[["domains.nameservers","domains.renew"]],"description":"The full new list, replacing any you had. Empty leaves customers read-only","anyOf":[{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]}},{"type":"null"}]},"products":{"examples":[["domains"]],"description":"The full new list, replacing any you had. Only lines your own account can order: ticking one here never grants one you do not hold","anyOf":[{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]}},{"type":"null"}]}}}}}},"responses":{"200":{"description":"How your customer portal and storefront look, and what your customers may do there","content":{"application/json":{"schema":{"description":"How your customer portal and storefront look, and what your customers may do there","type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"},"url":{"type":"string","examples":["https://northwind.portal.example"],"description":"Where this side of the account answers to customers. Read-only, and computed from your slug: live and sandbox have their own"},"publishedAt":{"format":"date-time","examples":[null],"description":"When the builder’s draft was last published to this live document. Null means never, through the builder - set only by `POST /account/portal/publish`","type":["string","null"]}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification","url","publishedAt"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/portal/draft":{"patch":{"operationId":"updateAccountPortalDraft","summary":"Update the customer portal draft","tags":["Customer portal"],"description":"The customer-portal builder’s own draft (design §4): every field `PATCH /account/portal` accepts, plus the builder’s own appearance, content and access fields. Written only here, never to your live portal - `POST /account/portal/publish` copies it across when you are ready. Send only what changes; `null` clears a field, putting it back on its default. Live and sandbox keep their own draft, same as the live portal.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"description":"Turning this off answers the same 404 as an address no reseller holds","type":["boolean","null"]},"brandName":{"examples":["Northwind"],"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"accentColor":{"examples":["#1d4ed8"],"anyOf":[{"type":"string","pattern":"^#[0-9a-f]{6}$"},{"type":"null"}]},"supportEmail":{"examples":["support@northwind.example"],"anyOf":[{"type":"string","maxLength":254,"format":"email"},{"type":"null"}]},"emailFromName":{"examples":["Northwind Support"],"anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"termsUrl":{"examples":["https://northwind.example/terms"],"anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"anyOf":[{"type":"string","maxLength":500,"format":"uri"},{"type":"null"}]},"selfSignup":{"type":["boolean","null"]},"allow":{"anyOf":[{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]}},{"type":"null"}]},"products":{"anyOf":[{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]}},{"type":"null"}]},"theme":{"anyOf":[{"type":"string","enum":["light","dark","auto"]},{"type":"null"}]},"fontPair":{"anyOf":[{"type":"string","enum":["geist","classic","mono"]},{"type":"null"}]},"headline":{"examples":["Find your domain"],"anyOf":[{"type":"string","minLength":1,"maxLength":80},{"type":"null"}]},"intro":{"examples":["Search a name across every ending we sell."],"anyOf":[{"type":"string","minLength":1,"maxLength":160},{"type":"null"}]},"banner":{"anyOf":[{"type":"string","minLength":1,"maxLength":140},{"type":"null"}]},"productOrder":{"anyOf":[{"maxItems":3,"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]}},{"type":"null"}]},"termsMode":{"anyOf":[{"type":"string","enum":["link","write"]},{"type":"null"}]},"termsText":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]},"privacyMode":{"anyOf":[{"type":"string","enum":["link","write"]},{"type":"null"}]},"privacyText":{"anyOf":[{"type":"string","minLength":1,"maxLength":20000},{"type":"null"}]},"faq":{"anyOf":[{"maxItems":50,"type":"array","items":{"type":"object","properties":{"question":{"type":"string","maxLength":100},"answer":{"type":"string","maxLength":500}},"required":["question","answer"]}},{"type":"null"}]},"pricesBeforeSignIn":{"type":["boolean","null"]},"requireEmailVerification":{"type":["boolean","null"]}}}}}},"responses":{"200":{"description":"The portal builder’s own draft: what Publish will copy onto your live portal. Edited by `PATCH /account/portal/draft`, and only ever reaches customers once you publish it","content":{"application/json":{"schema":{"description":"The portal builder’s own draft: what Publish will copy onto your live portal. Edited by `PATCH /account/portal/draft`, and only ever reaches customers once you publish it","type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/portal/publish":{"post":{"operationId":"publishAccountPortal","summary":"Publish the customer portal draft","tags":["Customer portal"],"description":"Copies the customer-portal builder’s draft onto your live portal, whole: every field the draft holds, including the ones it holds at their default, replaces the matching field on the live document. Customers see the result at once. Live and sandbox publish their own draft, independently.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"portal":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"},"url":{"type":"string","examples":["https://northwind.portal.example"],"description":"Where this side of the account answers to customers. Read-only, and computed from your slug: live and sandbox have their own"},"publishedAt":{"format":"date-time","examples":[null],"description":"When the builder’s draft was last published to this live document. Null means never, through the builder - set only by `POST /account/portal/publish`","type":["string","null"]}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification","url","publishedAt"],"additionalProperties":false,"description":"How your customer portal and storefront look, and what your customers may do there"},"portalDraft":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification"],"additionalProperties":false,"description":"The portal builder’s own draft: what Publish will copy onto your live portal. Edited by `PATCH /account/portal/draft`, and only ever reaches customers once you publish it"}},"required":["portal","portalDraft"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/product-requests":{"post":{"operationId":"requestProduct","summary":"Ask for a product line","tags":["Account"],"description":"Asks for a product line (`numbers`, `domains` or `licences`) to be switched on for this account. Product lines are turned on by the platform; this records the ask, with when it was made, for the team to act on. Asking again keeps the first date. Refused with `product_already_on` for a line the account can already order.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"product":{"type":"string","enum":["domains","numbers","licences"]}},"required":["product"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"product":{"type":"string","enum":["domains","numbers","licences"]},"requestedAt":{"type":"string","format":"date-time"}},"required":["product","requestedAt"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `product_already_on`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `product_already_on`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"product_already_on","message":"This product is already switched on for your account","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/from-sandbox":{"post":{"operationId":"copySandboxSetup","summary":"Bring sandbox setup to live","tags":["Account"],"description":"Copies what was set up while trying the account in the sandbox to live, for the parts asked for: `prices` (every price list, with its rules), `portal` (the customer portal’s branding and content, published and draft) and `business` (the details printed on invoices). Once, before live has sold anything; refused with `live_in_use` after. Never overwrites: a part live already has is left as it is, and the response says which parts were copied. Promotions, customers and which customer is on which list stay behind, as sandbox customers are not live ones.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prices":{"default":false,"type":"boolean"},"portal":{"default":false,"type":"boolean"},"business":{"default":false,"type":"boolean"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"prices":{"type":"integer","description":"How many price lists were copied"},"portal":{"type":"boolean"},"business":{"type":"boolean"}},"required":["prices","portal","business"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `live_in_use`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `live_in_use`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"live_in_use","message":"Live has already made sales, so it keeps its own setup","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `live_only`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `live_only`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"live_only","message":"Sandbox setup is brought over from the live side","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/portal/discard":{"post":{"operationId":"discardAccountPortal","summary":"Discard the customer portal draft","tags":["Customer portal"],"description":"Overwrites the customer-portal builder’s draft with your live portal’s own values, exactly - restoring the last published state. Your live portal is untouched either way.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"portal":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"},"url":{"type":"string","examples":["https://northwind.portal.example"],"description":"Where this side of the account answers to customers. Read-only, and computed from your slug: live and sandbox have their own"},"publishedAt":{"format":"date-time","examples":[null],"description":"When the builder’s draft was last published to this live document. Null means never, through the builder - set only by `POST /account/portal/publish`","type":["string","null"]}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification","url","publishedAt"],"additionalProperties":false,"description":"How your customer portal and storefront look, and what your customers may do there"},"portalDraft":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification"],"additionalProperties":false,"description":"The portal builder’s own draft: what Publish will copy onto your live portal. Edited by `PATCH /account/portal/draft`, and only ever reaches customers once you publish it"}},"required":["portal","portalDraft"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/portal/logo":{"post":{"operationId":"uploadAccountPortalLogo","summary":"Upload a customer portal logo","tags":["Customer portal"],"description":"Stores an uploaded PNG, JPEG or WebP logo (at most 256 KB) and writes its own address onto the customer-portal builder’s draft `logoUrl` field (`logoDarkUrl` with `variant: \"dark\"`), seeding the rest of the draft from your live portal the first time it is ever written, same as `PATCH /account/portal/draft`. Paste a URL instead through that route for an SVG logo - there is no sanitizer here for one. `POST /account/portal/publish` copies the result onto your live portal, same as any other draft field.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataUrl":{"type":"string","description":"A `data:` URL, such as `FileReader.readAsDataURL()` produces in a browser. The declared mime type in it is ignored - the real type is read from the file’s own bytes"},"variant":{"default":"light","description":"`dark` for the logo drawn on a dark background","type":"string","enum":["light","dark"]}},"required":["dataUrl"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"portalDraft":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether the portal and storefront answer at all. On until turned off"},"brandName":{"examples":["Northwind"],"description":"Shown to customers instead of your account name. Null, your account name","type":["string","null"]},"logoUrl":{"examples":["https://northwind.example/logo.svg"],"description":"`https` only","type":["string","null"]},"logoDarkUrl":{"examples":["https://northwind.example/logo-white.svg"],"description":"The logo on a dark background, `https` only. Null, `logoUrl` on both","type":["string","null"]},"accentColor":{"examples":["#1d4ed8"],"description":"`#rrggbb`, rendered as a CSS custom property","type":["string","null"]},"supportEmail":{"examples":["support@northwind.example"],"description":"Where customers are told to write. Null, your billing email","type":["string","null"]},"emailFromName":{"examples":["Northwind Support"],"description":"The from-name on mail to your customers. Null, your brand name","type":["string","null"]},"termsUrl":{"examples":["https://northwind.example/terms"],"type":["string","null"]},"privacyUrl":{"examples":["https://northwind.example/privacy"],"type":["string","null"]},"selfSignup":{"type":"boolean","description":"Whether a storefront visitor may open an account unasked. Off until turned on"},"allow":{"type":"array","items":{"type":"string","enum":["domains.nameservers","domains.contacts","domains.lock","domains.renew","numbers.renew","store.domains","store.numbers","store.licences"]},"description":"What your customers may do in the portal. Empty means read-only"},"products":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The product lines your customers may browse. Empty means none"},"theme":{"type":"string","enum":["light","dark","auto"],"description":"`auto` forces nothing and follows the visitor’s own device, which is what happens with no field at all. `light`/`dark` force the portal, next split issue - this field is persisted and shown in the builder’s own preview now"},"fontPair":{"type":"string","enum":["geist","classic","mono"],"description":"`geist` is today’s faces, unchanged. Default `geist`"},"headline":{"examples":["Find your domain"],"description":"The storefront home page’s own heading. Null, the builder’s computed default","type":["string","null"]},"intro":{"examples":["Search a name across every ending we sell."],"description":"One or two sentences under the headline. Null, the builder’s computed default","type":["string","null"]},"banner":{"description":"A short announcement above the products. Null means none, same as today","type":["string","null"]},"productOrder":{"type":"array","items":{"type":"string","enum":["domains","numbers","licences"]},"description":"The order your product lines are drawn in, filtered to whichever are in `products`. Default is domains, numbers, licences, filtered the same way - today’s order"},"termsMode":{"type":"string","enum":["link","write"],"description":"Whether Terms is a link to your own page or a page written here. Default `link`"},"termsText":{"description":"Your own words, shown when `termsMode` is `write`. Null until you write some","type":["string","null"]},"privacyMode":{"type":"string","enum":["link","write"],"description":"Whether Privacy is a link to your own page or a page written here. Default `link`"},"privacyText":{"description":"Your own words, shown when `privacyMode` is `write`. Null until you write some","type":["string","null"]},"faq":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"answer":{"type":"string"}},"required":["question","answer"],"additionalProperties":false},"description":"Questions and answers at the foot of the storefront home page. Empty means none"},"pricesBeforeSignIn":{"type":"boolean","description":"Whether a visitor sees prices before signing in. Default true, today’s real behaviour with no field at all. Not yet wired into the real pricing gate"},"requireEmailVerification":{"type":"boolean","description":"Whether a customer must confirm their email before they can sign in. Default true, today’s real behaviour with no field at all. Not yet wired into the real sign-in gate"}},"required":["enabled","brandName","logoUrl","logoDarkUrl","accentColor","supportEmail","emailFromName","termsUrl","privacyUrl","selfSignup","allow","products","theme","fontPair","headline","intro","banner","productOrder","termsMode","termsText","privacyMode","privacyText","faq","pricesBeforeSignIn","requireEmailVerification"],"additionalProperties":false,"description":"The portal builder’s own draft: what Publish will copy onto your live portal. Edited by `PATCH /account/portal/draft`, and only ever reaches customers once you publish it"}},"required":["portalDraft"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `logo_too_large` or `logo_unsupported_type`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `logo_too_large` or `logo_unsupported_type`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"logo_too_large","message":"That image is larger than 256 KB","requestId":"req-4f"}},"example2":{"value":{"error":"logo_unsupported_type","message":"Upload a PNG, JPEG or WebP - paste a URL instead for an SVG logo.","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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. `autoRenewByDefault` turns auto-renew on for new registrations. `digestEnabled` turns the weekly expiry digest email off. 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"},"autoRenewByDefault":{"description":"New registrations renew themselves from your wallet","type":"boolean"},"digestEnabled":{"description":"The weekly email of domains expiring soon or failing to auto-renew","type":"boolean"}}}}}},"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"},"autoRenewByDefault":{"type":"boolean","description":"New registrations renew themselves from your wallet. Off until turned on"},"digestEnabled":{"type":"boolean","description":"The weekly email of domains expiring soon or failing to auto-renew. On until turned off"},"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 last updated these domain settings"}},"required":["defaultRegistrant","privacyByDefault","autoRenewByDefault","digestEnabled","actor"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/analytics":{"patch":{"operationId":"updateAccountAnalytics","summary":"Update analytics settings","tags":["Account"],"description":"Switches dashboard session replay off for this account, or back on. Has no effect on an account flagged `internal` in the admin panel, which never records whatever this is set to.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"replayEnabled":{"type":"boolean","description":"False stops every future dashboard recording"}},"required":["replayEnabled"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"replayEnabled":{"type":"boolean","description":"Whether the dashboard may send PostHog session replay for this account - off for every account flagged `internal` in the admin panel, whatever this reseller's own setting is, and otherwise this reseller's own choice. A rejected cookie banner or a deployment with no PostHog key configured sends nothing either way, which this field does not know about"}},"required":["replayEnabled"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/tax/rules":{"get":{"operationId":"getTaxRules","summary":"Get the tax rules","tags":["Tax"],"description":"Your own tax rules (issue #341): the first rule whose country, region and business all match a customer decides what a new invoice bills them. Rules are tried in this order. Empty is a valid, intentional configuration: every invoice carries no tax until you add one.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country":{"examples":["DE"],"type":"string","pattern":"^([A-Z]{2}|EU)$"},"region":{"examples":["Karnataka"],"type":"string","minLength":1,"maxLength":40},"business":{"description":"\"required\" matches only a customer with a currently-valid tax number, \"none\" only one without. Unset matches either","type":"string","enum":["required","none"]},"components":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"examples":["VAT"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000]}},"required":["name","rateBps"],"additionalProperties":false},"examples":[[{"name":"VAT","rateBps":2000}]]},"reverseCharge":{"description":"Zero tax; the invoice shows 0% and a legal note with both tax numbers instead","type":"boolean"}},"required":["components"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"updateTaxRules","summary":"Replace the tax rules","tags":["Tax"],"description":"Replaces the whole list, in the order they are tried. There is no id to patch one rule by: send every rule you want to keep. Turns the tax rules engine on for new invoices from now on, ahead of the older `defaultTaxBps`, even when sent empty.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"country":{"examples":["DE"],"type":"string","pattern":"^([A-Z]{2}|EU)$"},"region":{"examples":["Karnataka"],"type":"string","minLength":1,"maxLength":40},"business":{"description":"\"required\" matches only a customer with a currently-valid tax number, \"none\" only one without. Unset matches either","type":"string","enum":["required","none"]},"components":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"examples":["VAT"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000]}},"required":["name","rateBps"]},"examples":[[{"name":"VAT","rateBps":2000}]]},"reverseCharge":{"description":"Zero tax; the invoice shows 0% and a legal note with both tax numbers instead","type":"boolean"}},"required":["components"]}}},"required":["rules"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country":{"examples":["DE"],"type":"string","pattern":"^([A-Z]{2}|EU)$"},"region":{"examples":["Karnataka"],"type":"string","minLength":1,"maxLength":40},"business":{"description":"\"required\" matches only a customer with a currently-valid tax number, \"none\" only one without. Unset matches either","type":"string","enum":["required","none"]},"components":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"examples":["VAT"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000]}},"required":["name","rateBps"],"additionalProperties":false},"examples":[[{"name":"VAT","rateBps":2000}]]},"reverseCharge":{"description":"Zero tax; the invoice shows 0% and a legal note with both tax numbers instead","type":"boolean"}},"required":["components"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/tax/presets/{name}":{"post":{"operationId":"applyTaxPreset","summary":"Apply a tax rules preset","tags":["Tax"],"description":"A one-click starting point for the tax rules engine (issue #341), built from your home country and home state or region (`PATCH /account/billing`); set those first. Replaces the whole rule list. A starting point, not tax advice: check it with whoever handles your tax before relying on it.","parameters":[{"schema":{"type":"string","enum":["eu","uk","in","none"]},"in":"path","name":"name","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"country":{"examples":["DE"],"type":"string","pattern":"^([A-Z]{2}|EU)$"},"region":{"examples":["Karnataka"],"type":"string","minLength":1,"maxLength":40},"business":{"description":"\"required\" matches only a customer with a currently-valid tax number, \"none\" only one without. Unset matches either","type":"string","enum":["required","none"]},"components":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":40,"examples":["VAT"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000]}},"required":["name","rateBps"],"additionalProperties":false},"examples":[[{"name":"VAT","rateBps":2000}]]},"reverseCharge":{"description":"Zero tax; the invoice shows 0% and a legal note with both tax numbers instead","type":"boolean"}},"required":["components"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `home_country_required` or `home_region_required`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `home_country_required` or `home_region_required`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"home_country_required","message":"Set your home country first, in account billing settings","requestId":"req-4f"}},"example2":{"value":{"error":"home_region_required","message":"Set your home state or region first, in account billing settings","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/step-up":{"post":{"operationId":"stepUp","summary":"Re-prove a strong credential","tags":["Account"],"description":"Confirms a sensitive action by password (and a code, if two-factor is on). A passkey instead re-asserts through `/api/auth/passkey/verify-authentication`. Either one starts a short grace window during which a gated action proceeds without being asked again.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"password":{"type":"string","minLength":1},"code":{"type":"string","minLength":1},"backupCode":{"type":"string","minLength":1}},"required":["password"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"expiresAt":{"type":"string"}},"required":["ok","expiresAt"],"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` or `step_up_required`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized` or `step_up_required`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}},"example2":{"value":{"error":"step_up_required","message":"Confirm it is you before doing this again.","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/hostnames":{"get":{"operationId":"listAccountHostnames","summary":"List connected hostnames","tags":["Hostnames"],"description":"Every hostname this account has connected to its portal (issue #443).","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["hst_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"hostname":{"type":"string","examples":["shop.northwind.example"]},"kind":{"type":"string","enum":["subdomain","custom"],"description":"subdomain is a label under your own portal address; custom is a domain of yours"},"status":{"type":"string","enum":["pending","verified","failed"],"description":"pending until its CNAME is confirmed, or always verified for a subdomain"},"attempts":{"type":"integer","examples":[0],"description":"Failed CNAME checks so far"},"lastCheckedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"verifiedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"failure":{"examples":[null],"description":"Why the most recent check failed. Null once verified, and before the first check","type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"cnameTarget":{"examples":["portal.rhq.app"],"description":"What a `custom` hostname's CNAME must point at. Null for a `subdomain` one","type":["string","null"]}},"required":["id","hostname","kind","status","attempts","lastCheckedAt","verifiedAt","failure","createdAt","cnameTarget"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"createAccountHostname","summary":"Connect a hostname","tags":["Hostnames"],"description":"Claims a hostname for this account. A `custom` hostname stays `pending` until its CNAME is confirmed (`POST .../:id/check`, or the worker checking in the background); a `subdomain` one is verified at once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hostname":{"type":"string","minLength":1,"maxLength":253,"examples":["shop.northwind.example"]},"kind":{"type":"string","enum":["subdomain","custom"]}},"required":["hostname","kind"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["hst_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"hostname":{"type":"string","examples":["shop.northwind.example"]},"kind":{"type":"string","enum":["subdomain","custom"],"description":"subdomain is a label under your own portal address; custom is a domain of yours"},"status":{"type":"string","enum":["pending","verified","failed"],"description":"pending until its CNAME is confirmed, or always verified for a subdomain"},"attempts":{"type":"integer","examples":[0],"description":"Failed CNAME checks so far"},"lastCheckedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"verifiedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"failure":{"examples":[null],"description":"Why the most recent check failed. Null once verified, and before the first check","type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"cnameTarget":{"examples":["portal.rhq.app"],"description":"What a `custom` hostname's CNAME must point at. Null for a `subdomain` one","type":["string","null"]}},"required":["id","hostname","kind","status","attempts","lastCheckedAt","verifiedAt","failure","createdAt","cnameTarget"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"409":{"description":"The request conflicts with the current state. `error` is `hostname_taken`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `hostname_taken`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"hostname_taken","message":"This hostname is already in use","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_domain` or `apex_hostname`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_domain` or `apex_hostname`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"invalid_domain","message":"Enter a domain such as acme.com","requestId":"req-4f"}},"example2":{"value":{"error":"apex_hostname","message":"Connect a subdomain, such as shop.acme.com, rather than the bare domain","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/hostnames/{id}":{"delete":{"operationId":"deleteAccountHostname","summary":"Disconnect a hostname","tags":["Hostnames"],"description":"Stops this hostname resolving to this account, at once.","parameters":[{"schema":{"type":"string"},"example":"hst_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"204":{"description":"Disconnected"},"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/hostnames/{id}/check":{"post":{"operationId":"checkAccountHostname","summary":"Check a hostname now","tags":["Hostnames"],"description":"Runs the CNAME check immediately, the same one the worker runs in the background, and reaches it even if repeated failure has parked it.","parameters":[{"schema":{"type":"string"},"example":"hst_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["hst_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"hostname":{"type":"string","examples":["shop.northwind.example"]},"kind":{"type":"string","enum":["subdomain","custom"],"description":"subdomain is a label under your own portal address; custom is a domain of yours"},"status":{"type":"string","enum":["pending","verified","failed"],"description":"pending until its CNAME is confirmed, or always verified for a subdomain"},"attempts":{"type":"integer","examples":[0],"description":"Failed CNAME checks so far"},"lastCheckedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"verifiedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"failure":{"examples":[null],"description":"Why the most recent check failed. Null once verified, and before the first check","type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"cnameTarget":{"examples":["portal.rhq.app"],"description":"What a `custom` hostname's CNAME must point at. Null for a `subdomain` one","type":["string","null"]}},"required":["id","hostname","kind","status","attempts","lastCheckedAt","verifiedAt","failure","createdAt","cnameTarget"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/branded-nameservers":{"get":{"operationId":"getBrandedNameservers","summary":"Get your branded nameserver set","tags":["Branded nameservers"],"description":"Your one branded nameserver set (#344), or null if you have none yet.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"set":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["bns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"carrierDomainId":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"carrierDomain":{"type":"string","examples":["acme-hosting.com"]},"names":{"type":"array","items":{"type":"string"},"examples":[["ns1.acme-hosting.com","ns2.acme-hosting.com"]],"description":"2 to 4 hostnames under the carrier domain"},"status":{"type":"string","enum":["pending","ready","failed"],"description":"ready once every name resolves to its expected addresses"},"checks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","examples":["ns1.acme-hosting.com"]},"status":{"type":"string","enum":["pending","ok","failed"]},"lastCheckedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"failure":{"examples":[null],"description":"Why the most recent check failed. Null once ok, and before the first check","type":["string","null"]}},"required":["name","status","lastCheckedAt","failure"],"additionalProperties":false}},"usedByCount":{"type":"integer","examples":[0],"description":"Domains in your account currently using these names as their nameservers"},"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","carrierDomainId","carrierDomain","names","status","checks","usedByCount","createdAt","updatedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["set"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"createBrandedNameservers","summary":"Create your branded nameserver set","tags":["Branded nameservers"],"description":"2 to 4 hostnames under a domain you hold with us, each given a host record and checked at once, so a correctly-pointed set comes back already ready rather than making you poll. Refused while you already have a set: remove it first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"carrierDomainId":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"A domain you hold with us"},"names":{"type":"array","items":{"type":"string","minLength":4,"maxLength":253},"examples":[["ns1.acme-hosting.com","ns2.acme-hosting.com"]],"description":"Each a hostname under the carrier domain, like ns1.acme-hosting.com"}},"required":["carrierDomainId","names"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["bns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"carrierDomainId":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"carrierDomain":{"type":"string","examples":["acme-hosting.com"]},"names":{"type":"array","items":{"type":"string"},"examples":[["ns1.acme-hosting.com","ns2.acme-hosting.com"]],"description":"2 to 4 hostnames under the carrier domain"},"status":{"type":"string","enum":["pending","ready","failed"],"description":"ready once every name resolves to its expected addresses"},"checks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","examples":["ns1.acme-hosting.com"]},"status":{"type":"string","enum":["pending","ok","failed"]},"lastCheckedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"failure":{"examples":[null],"description":"Why the most recent check failed. Null once ok, and before the first check","type":["string","null"]}},"required":["name","status","lastCheckedAt","failure"],"additionalProperties":false}},"usedByCount":{"type":"integer","examples":[0],"description":"Domains in your account currently using these names as their nameservers"},"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","carrierDomainId","carrierDomain","names","status","checks","usedByCount","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `branded_nameservers_exists`, `domain_not_modifiable`, or `registrar_refused`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `branded_nameservers_exists`, `domain_not_modifiable`, 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"]},"examples":{"example1":{"value":{"error":"branded_nameservers_exists","message":"Remove the current branded nameserver set before creating another","requestId":"req-4f"}},"example2":{"value":{"error":"domain_not_modifiable","message":"This domain is not finished registering yet","requestId":"req-4f"}},"example3":{"value":{"error":"registrar_refused","message":"The registrar refused this change to the domain","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_branded_nameserver_count`, or `host_not_under_domain`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_branded_nameserver_count`, or `host_not_under_domain`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_branded_nameserver_count","message":"Give 2 to 4 nameservers","requestId":"req-4f"}},"example3":{"value":{"error":"host_not_under_domain","message":"The host must be a hostname under this exact domain","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `host_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `host_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":"host_failed","message":"The registrar could not complete this host change","requestId":"req-4f"}}}}}},"delete":{"operationId":"deleteBrandedNameservers","summary":"Remove your branded nameserver set","tags":["Branded nameservers"],"description":"Puts every domain still pointed at these names back on the default nameservers, deletes each host record at the registrar, and removes the set.","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/branded-nameservers/check":{"post":{"operationId":"checkBrandedNameservers","summary":"Check your branded nameserver set","tags":["Branded nameservers"],"description":"Checks that each name still resolves, from outside, to the addresses its host record was given, and updates its status accordingly.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["bns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"carrierDomainId":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"carrierDomain":{"type":"string","examples":["acme-hosting.com"]},"names":{"type":"array","items":{"type":"string"},"examples":[["ns1.acme-hosting.com","ns2.acme-hosting.com"]],"description":"2 to 4 hostnames under the carrier domain"},"status":{"type":"string","enum":["pending","ready","failed"],"description":"ready once every name resolves to its expected addresses"},"checks":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","examples":["ns1.acme-hosting.com"]},"status":{"type":"string","enum":["pending","ok","failed"]},"lastCheckedAt":{"format":"date-time","examples":[null],"type":["string","null"]},"failure":{"examples":[null],"description":"Why the most recent check failed. Null once ok, and before the first check","type":["string","null"]}},"required":["name","status","lastCheckedAt","failure"],"additionalProperties":false}},"usedByCount":{"type":"integer","examples":[0],"description":"Domains in your account currently using these names as their nameservers"},"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","carrierDomainId","carrierDomain","names","status","checks","usedByCount","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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","debit","writeoff","transfer_out","transfer_in","margin","clawback"]},"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","debit","writeoff","transfer_out","transfer_in","margin","clawback"],"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","enum":["hold","domain","domain_transfer","domain_privacy","licence","mailbox","mailbox_domain","number_order","number_rental","reconciliation_case","stripe_checkout_session","stripe_refund","stripe_dispute"]},"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"]},"receiptUrl":{"examples":[null],"description":"Stripe’s own receipt link, on a card top-up only","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","receiptUrl","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/top-ups":{"post":{"operationId":"createWalletTopUp","summary":"Start a card top-up","tags":["Wallet"],"description":"Opens a Stripe Checkout session for adding funds by card. The wallet is credited once Stripe confirms the payment - from the webhook, never from this response.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","minimum":500,"maximum":500000,"examples":[10000],"description":"Charged to the card, in cents"}},"required":["amount"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["wtp_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"url":{"type":"string","format":"uri","description":"Open this to pay"},"amount":{"type":"integer","description":"Charged to the card, in cents"},"creditAmount":{"type":"integer","description":"What the wallet is credited once Stripe confirms the payment"}},"required":["id","url","amount","creditAmount"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `stripe_not_configured`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `stripe_not_configured`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"stripe_not_configured","message":"Card top-ups are not available for this deployment","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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},"country":{"description":"Where this customer is, for the tax rules engine to match a rule against (issue #341)","type":"string","pattern":"^[A-Z]{2}$","examples":["US"]},"region":{"examples":["Karnataka"],"description":"This customer's state or region, for a rule that names one","type":"string","minLength":1,"maxLength":40},"taxOverride":{"description":"This customer’s own exception to the account’s tax rules: exempt, or a fixed rate","oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["exempt"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["fixed"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[500]},"name":{"examples":["Flat fee"],"description":"Shown on the invoice. Unset, \"Tax\"","type":"string","minLength":1,"maxLength":24}},"required":["type","rateBps"]}]},"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"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}],"examples":[null],"description":"Where this customer is, for the tax rules engine to match a rule against (issue #341)"},"region":{"examples":[null],"description":"This customer's state or region, for a rule that names one","type":["string","null"]},"taxOverride":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["exempt"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["fixed"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[500]},"name":{"examples":["Flat fee"],"description":"Shown on the invoice. Unset, \"Tax\"","type":"string","minLength":1,"maxLength":24}},"required":["type","rateBps"],"additionalProperties":false}]},{"type":"null"}],"examples":[null],"description":"This customer’s own exception to the account’s tax rules. Null, the rules decide"},"taxIdCheck":{"anyOf":[{"type":"object","properties":{"valid":{"description":"null is \"could not be checked\" - VIES was unreachable, not that the number is bad","type":["boolean","null"]},"checkedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["valid","checkedAt"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"The result of the last VIES check on `taxId`, and when. Null, never checked"},"taxIdTrusted":{"type":"boolean","description":"Whether you chose to treat a could-not-be-checked (`taxIdCheck.valid === null`) number as valid anyway"},"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","country","region","taxOverride","taxIdCheck","taxIdTrusted","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}],"examples":[null],"description":"Where this customer is, for the tax rules engine to match a rule against (issue #341)"},"region":{"examples":[null],"description":"This customer's state or region, for a rule that names one","type":["string","null"]},"taxOverride":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["exempt"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["fixed"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[500]},"name":{"examples":["Flat fee"],"description":"Shown on the invoice. Unset, \"Tax\"","type":"string","minLength":1,"maxLength":24}},"required":["type","rateBps"],"additionalProperties":false}]},{"type":"null"}],"examples":[null],"description":"This customer’s own exception to the account’s tax rules. Null, the rules decide"},"taxIdCheck":{"anyOf":[{"type":"object","properties":{"valid":{"description":"null is \"could not be checked\" - VIES was unreachable, not that the number is bad","type":["boolean","null"]},"checkedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["valid","checkedAt"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"The result of the last VIES check on `taxId`, and when. Null, never checked"},"taxIdTrusted":{"type":"boolean","description":"Whether you chose to treat a could-not-be-checked (`taxIdCheck.valid === null`) number as valid anyway"},"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","country","region","taxOverride","taxIdCheck","taxIdTrusted","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}],"examples":[null],"description":"Where this customer is, for the tax rules engine to match a rule against (issue #341)"},"region":{"examples":[null],"description":"This customer's state or region, for a rule that names one","type":["string","null"]},"taxOverride":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["exempt"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["fixed"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[500]},"name":{"examples":["Flat fee"],"description":"Shown on the invoice. Unset, \"Tax\"","type":"string","minLength":1,"maxLength":24}},"required":["type","rateBps"],"additionalProperties":false}]},{"type":"null"}],"examples":[null],"description":"This customer’s own exception to the account’s tax rules. Null, the rules decide"},"taxIdCheck":{"anyOf":[{"type":"object","properties":{"valid":{"description":"null is \"could not be checked\" - VIES was unreachable, not that the number is bad","type":["boolean","null"]},"checkedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["valid","checkedAt"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"The result of the last VIES check on `taxId`, and when. Null, never checked"},"taxIdTrusted":{"type":"boolean","description":"Whether you chose to treat a could-not-be-checked (`taxIdCheck.valid === null`) number as valid anyway"},"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","country","region","taxOverride","taxIdCheck","taxIdTrusted","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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. Changing `taxId` itself clears `taxIdCheck` and `taxIdTrusted`: a check and a trust decision belong to the number that was checked, not to whatever replaces it.","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"}]},"country":{"description":"Where this customer is, for the tax rules engine (issue #341)","anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}]},"region":{"examples":["Karnataka"],"description":"This customer's state or region, for a rule that names one","anyOf":[{"type":"string","minLength":1,"maxLength":40},{"type":"null"}]},"taxOverride":{"description":"`null` puts this customer back on the account rules","anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["exempt"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["fixed"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[500]},"name":{"examples":["Flat fee"],"description":"Shown on the invoice. Unset, \"Tax\"","type":"string","minLength":1,"maxLength":24}},"required":["type","rateBps"]}]},{"type":"null"}]},"taxIdTrusted":{"description":"Treats a `taxIdCheck.valid === null` number (VIES could not be reached) as valid anyway. Ignored when `taxId` changes in the same request","type":"boolean"},"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"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}],"examples":[null],"description":"Where this customer is, for the tax rules engine to match a rule against (issue #341)"},"region":{"examples":[null],"description":"This customer's state or region, for a rule that names one","type":["string","null"]},"taxOverride":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["exempt"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["fixed"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[500]},"name":{"examples":["Flat fee"],"description":"Shown on the invoice. Unset, \"Tax\"","type":"string","minLength":1,"maxLength":24}},"required":["type","rateBps"],"additionalProperties":false}]},{"type":"null"}],"examples":[null],"description":"This customer’s own exception to the account’s tax rules. Null, the rules decide"},"taxIdCheck":{"anyOf":[{"type":"object","properties":{"valid":{"description":"null is \"could not be checked\" - VIES was unreachable, not that the number is bad","type":["boolean","null"]},"checkedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["valid","checkedAt"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"The result of the last VIES check on `taxId`, and when. Null, never checked"},"taxIdTrusted":{"type":"boolean","description":"Whether you chose to treat a could-not-be-checked (`taxIdCheck.valid === null`) number as valid anyway"},"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","country","region","taxOverride","taxIdCheck","taxIdTrusted","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/tax-id/validate":{"post":{"operationId":"validateCustomerTaxId","summary":"Validate a tax number","tags":["Customers"],"description":"Checks this customer's `taxId` against the EU Commission's VIES service and stores the result with its date. VIES being unreachable is not a failure of the customer: the answer is `valid: null`, \"could not be checked\", the number is kept, and `taxIdTrusted` on `PATCH /customers/:id` is how you choose to treat it as valid anyway.","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"]},"country":{"anyOf":[{"type":"string","pattern":"^[A-Z]{2}$","examples":["US"],"description":"ISO 3166-1 alpha-2 country code, for example US or GB"},{"type":"null"}],"examples":[null],"description":"Where this customer is, for the tax rules engine to match a rule against (issue #341)"},"region":{"examples":[null],"description":"This customer's state or region, for a rule that names one","type":["string","null"]},"taxOverride":{"anyOf":[{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["exempt"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["fixed"]},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[500]},"name":{"examples":["Flat fee"],"description":"Shown on the invoice. Unset, \"Tax\"","type":"string","minLength":1,"maxLength":24}},"required":["type","rateBps"],"additionalProperties":false}]},{"type":"null"}],"examples":[null],"description":"This customer’s own exception to the account’s tax rules. Null, the rules decide"},"taxIdCheck":{"anyOf":[{"type":"object","properties":{"valid":{"description":"null is \"could not be checked\" - VIES was unreachable, not that the number is bad","type":["boolean","null"]},"checkedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["valid","checkedAt"],"additionalProperties":false},{"type":"null"}],"examples":[null],"description":"The result of the last VIES check on `taxId`, and when. Null, never checked"},"taxIdTrusted":{"type":"boolean","description":"Whether you chose to treat a could-not-be-checked (`taxIdCheck.valid === null`) number as valid anyway"},"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","country","region","taxOverride","taxIdCheck","taxIdTrusted","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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_eu`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_eu`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_eu","message":"This customer needs a tax number and an EU country to check it against VIES","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/overview":{"get":{"operationId":"getOverview","summary":"Get the account overview","tags":["Account"],"description":"What you hold, what needs you and what renews by itself over the next 30 days, counted across every page. Each part your role cannot see comes back empty.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"counts":{"type":"object","properties":{"numbers":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Active numbers. Null without `product.read`"},"domains":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Every domain the domains list counts. Null without `product.read`"},"seats":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Mailbox seats across licences not cancelled. Null without `product.read`"},"mailboxes":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Google mailboxes paid for: set up, or being set up. Null without `product.read`"},"customers":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Customers. Null without `customer.read`"}},"required":["numbers","domains","seats","mailboxes","customers"],"additionalProperties":false,"description":"How much you hold"},"attention":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["licence_unpaid","licence_stalled","mailbox_unpaid","mailbox_nameservers","mailbox_failed","domain_redemption","domain_expiring","domain_validation","number_ending"],"description":"`licence_unpaid`: a month could not be charged. `licence_stalled`: the mailboxes never came up. `mailbox_unpaid`: a mailbox domain's month could not be charged; `at` is when it and its mailboxes are deleted. `mailbox_nameservers`: a domain registered elsewhere still waits on its nameservers. `mailbox_failed`: a mailbox domain never pointed at them. `domain_redemption`: past its renewal window, only a restore brings it back. `domain_expiring`: active, auto-renew off, expiring within 30 days. `domain_validation`: waiting on the registrant to validate. `number_ending`: active, auto-renew off, stopping within a day"},"count":{"type":"integer","examples":[4],"description":"How many match in total"},"sample":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["northwind-telecom.com"],"description":"The domain, the licence's domain, or the number in digits with no plus"},"at":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When it lapses, ends or first went unpaid. Null for a kind with no date of its own"},"amount":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440]},{"type":"null"}],"description":"What is owed, in minor units: only for an unpaid licence, null for every other kind"}},"required":["id","name","at","amount"],"additionalProperties":false},"description":"Up to 3 of them, the most urgent first"}},"required":["kind","count","sample"],"additionalProperties":false},"description":"What needs you, grouped by kind in a fixed order, only the kinds with something in them. Empty without `product.read`"},"renewals":{"anyOf":[{"type":"object","properties":{"domains":{"type":"object","properties":{"count":{"type":"integer","examples":[3]},"amount":{"type":"integer","minimum":0,"examples":[1440],"description":"What it will charge in total, in minor units"}},"required":["count","amount"],"additionalProperties":false,"description":"Domains with auto-renew on due within 30 days, as `GET /v1/domains/renewal-forecast`"},"numbers":{"type":"object","properties":{"count":{"type":"integer","examples":[3]},"amount":{"type":"integer","minimum":0,"examples":[1440],"description":"What it will charge in total, in minor units"}},"required":["count","amount"],"additionalProperties":false,"description":"Active numbers with auto-renew on ending within 30 days"},"licences":{"type":"object","properties":{"count":{"type":"integer","examples":[3]},"amount":{"type":"integer","minimum":0,"examples":[1440],"description":"What it will charge in total, in minor units"}},"required":["count","amount"],"additionalProperties":false,"description":"Active licences not set to cancel whose month ends within 30 days, every seat counted"}},"required":["domains","numbers","licences"],"additionalProperties":false},{"type":"null"}],"description":"What renews by itself from your wallet over the next 30 days. Null without `product.read`"}},"required":["counts","attention","renewals"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/activity":{"get":{"operationId":"listActivity","summary":"List activity","tags":["Activity"],"description":"Every change made inside your account: who did it, what they did, to what, when and from where. Newest first. Kept for 13 months and then removed. Readable with a dashboard session only: these records name your colleagues, so no API key reaches this route, whatever its level.","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":"usr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"actorId","required":false,"description":"A colleague's user id or an API key id"},{"schema":{"type":"string","enum":["user","api_key","system"]},"example":"system","in":"query","name":"actorKind","required":false,"description":"Everything done by a person, by an API key, or by us - `system` is what the renewals and the billing runs that need nobody present are filed under, and they carry no `actorId` to ask for instead"},{"schema":{"type":"string","enum":["account.analytics_update","account.billing_update","account.branded_nameservers_create","account.branded_nameservers_check","account.branded_nameservers_remove","account.domain_defaults_update","account.hostname_check","account.hostname_claim","account.hostname_delete","account.portal_update","account.portal_draft_update","account.portal_publish","account.portal_discard","account.sandbox_copy","account.product_request","account.tax_preset_apply","account.tax_rules_update","api_key.create","api_key.revoke","api_key.update","auth.passkey_add","auth.passkey_remove","auth.sign_in","auth.sign_in_failed","auth.step_up","auth.step_up_failed","billing_run.commit","billing_run.create","billing_run.exclude","credit_note.create","credit_note.share","credit_note.unshare","customer.contract_rules_update","customer.create","customer.invite","customer.tax_id_validate","customer.update","domain.auth_code","domain.delete","domain.dns_record_create","domain.dns_record_delete","domain.dns_record_update","domain.dns_records_replace","domain.dns_toggle","domain.dnssec_keys_set","domain.email_forwarding_set","domain.host_create","domain.host_delete","domain.host_update","domain.register","domain.renew","domain.resend_validation","domain.restore","domain.transfer_cancel","domain.transfer_start","domain.update","domain.url_forwarding_set","invoice.apply_credit","invoice.create","invoice.pay","invoice.share","invoice.unshare","invoice.void","licence.cancel","licence.order","licence.provisioning_failed","licence.renew","licence.update","licence.users_add","mailbox.client_id_grant","mailbox.credentials_view","mailbox.dmarc_set","mailbox.dns_change","mailbox.domain_connect","mailbox.domain_delete","mailbox.domain_update","mailbox.forwarding_set","mailbox.nameservers_regenerate","mailbox.order","mailbox.totp_view","mailbox.update","mcp_connection.disconnect","number.cancel","number.order","number.renew","number.update","payment.create","payment.share","payment.unshare","price_list.create","price_list.delete","price_list.update","promotion.create","promotion.delete","promotion.update","refund.create","sandbox.number_message","subreseller.fund","subreseller.invite","subreseller.invite_cancel","subreseller.price_list_update","subreseller.withdraw","team.invite","team.invite_cancel","team.remove","team.role_change","wallet.sandbox_topup","wallet.topup_start","webhook.create","webhook.delete","webhook.redeliver"]},"in":"query","name":"action","required":false},{"schema":{"type":"string","enum":["account","api_key","auth","billing_run","credit_note","customer","domain","invoice","licence","mailbox","mcp_connection","number","payment","price_list","promotion","refund","sandbox","subreseller","team","wallet","webhook"]},"example":"customer","in":"query","name":"resource","required":false,"description":"Every action on this resource, such as every `customer.*` one"},{"schema":{"type":"string","format":"date-time"},"example":"2026-10-07T11:04:31.000Z","in":"query","name":"from","required":false,"description":"Only records 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 records before this moment"},{"schema":{"type":"string","enum":["ok","denied","error"]},"in":"query","name":"outcome","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":["act_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"at":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"actor":{"type":"object","properties":{"kind":{"type":"string","enum":["user","api_key","system"],"description":"A colleague in the dashboard, an API key, or our own worker"},"id":{"examples":["usr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"The user id or the API key id. Null for `system`","type":["string","null"]},"label":{"examples":["Jo Bloggs"],"description":"What to show: the colleague's display name, or the API key's name - never its value, which is not stored anywhere in a readable form. Null when they have set none","type":["string","null"]}},"required":["kind","id","label"],"additionalProperties":false},"action":{"type":"string","enum":["account.analytics_update","account.billing_update","account.branded_nameservers_create","account.branded_nameservers_check","account.branded_nameservers_remove","account.domain_defaults_update","account.hostname_check","account.hostname_claim","account.hostname_delete","account.portal_update","account.portal_draft_update","account.portal_publish","account.portal_discard","account.sandbox_copy","account.product_request","account.tax_preset_apply","account.tax_rules_update","api_key.create","api_key.revoke","api_key.update","auth.passkey_add","auth.passkey_remove","auth.sign_in","auth.sign_in_failed","auth.step_up","auth.step_up_failed","billing_run.commit","billing_run.create","billing_run.exclude","credit_note.create","credit_note.share","credit_note.unshare","customer.contract_rules_update","customer.create","customer.invite","customer.tax_id_validate","customer.update","domain.auth_code","domain.delete","domain.dns_record_create","domain.dns_record_delete","domain.dns_record_update","domain.dns_records_replace","domain.dns_toggle","domain.dnssec_keys_set","domain.email_forwarding_set","domain.host_create","domain.host_delete","domain.host_update","domain.register","domain.renew","domain.resend_validation","domain.restore","domain.transfer_cancel","domain.transfer_start","domain.update","domain.url_forwarding_set","invoice.apply_credit","invoice.create","invoice.pay","invoice.share","invoice.unshare","invoice.void","licence.cancel","licence.order","licence.provisioning_failed","licence.renew","licence.update","licence.users_add","mailbox.client_id_grant","mailbox.credentials_view","mailbox.dmarc_set","mailbox.dns_change","mailbox.domain_connect","mailbox.domain_delete","mailbox.domain_update","mailbox.forwarding_set","mailbox.nameservers_regenerate","mailbox.order","mailbox.totp_view","mailbox.update","mcp_connection.disconnect","number.cancel","number.order","number.renew","number.update","payment.create","payment.share","payment.unshare","price_list.create","price_list.delete","price_list.update","promotion.create","promotion.delete","promotion.update","refund.create","sandbox.number_message","subreseller.fund","subreseller.invite","subreseller.invite_cancel","subreseller.price_list_update","subreseller.withdraw","team.invite","team.invite_cancel","team.remove","team.role_change","wallet.sandbox_topup","wallet.topup_start","webhook.create","webhook.delete","webhook.redeliver"],"examples":["customer.create"],"description":"What happened, as `<resource>.<verb>`"},"target":{"anyOf":[{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},{"type":"null"}],"examples":[{"type":"customer","id":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"}],"description":"What it was done to. Null when the change has no one subject, such as the account itself"},"ip":{"examples":["203.0.113.42"],"description":"Null for a change nothing requested, such as an auto-renewal","type":["string","null"]},"userAgent":{"examples":[null],"type":["string","null"]},"requestId":{"examples":["req-4f"],"description":"For joining to logs and traces. Null for the same reason as `ip`","type":["string","null"]},"before":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"examples":[null],"description":"What moved, before the change, for a settings or a price change. Null otherwise"},"after":{"anyOf":[{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},{"type":"null"}],"examples":[null],"description":"What moved, after the change, for a settings or a price change. Null otherwise"},"outcome":{"type":"string","enum":["ok","denied","error"],"description":"`denied` is a role or a credential that was not allowed to act; `error` failed on our side"},"errorCode":{"examples":[null],"description":"Set when `outcome` is not `ok`","type":["string","null"]}},"required":["id","at","actor","action","target","ip","userAgent","requestId","before","after","outcome","errorCode"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 and durations 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"},"inboundVoice":{"type":"boolean","description":"Whether numbers are on offer where incoming calls are transcribed and delivered as messages; nothing can be answered or dialled"}},"required":["countries","products","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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, promotions counted. A coupon that cannot be used is simply not applied here.","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"},{"schema":{"type":"string","minLength":1,"maxLength":40},"example":"LAUNCH25","in":"query","name":"coupon","required":false,"description":"Also count the promotion this coupon unlocks, as an order sending it would"}],"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"},"customerNormalPrice":{"examples":[1800],"description":"What the customer pays with no promotion, in `customerCurrency`. The same as `customerPrice` when no promotion applied. Only when you ask with `customerId`","anyOf":[{"type":"integer"},{"type":"null"}]},"customerPromotionEndsAt":{"examples":["2026-12-01T00:00:00.000Z"],"description":"When the promotion behind `customerPrice` ends. Null when none applied. Only when you ask with `customerId`","anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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. A `coupon` is checked before anything is bought, so an order it cannot be used on is refused with nothing charged, unless you send `couponOptional`.","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"},"receiveCalls":{"description":"Ask for numbers where incoming calls are transcribed and delivered as messages, where `inboundVoice` is on offer; nothing can be answered or dialled","type":"boolean"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"Required: every purchase belongs to one of your customers"},"coupon":{"description":"A coupon code, unlocking the promotion it belongs to for this order. A promotion everyone on the list gets needs no code","type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"]},"couponOptional":{"default":false,"description":"Place the order at the normal price when the coupon cannot be used, instead of refusing it","type":"boolean"}},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","createdAt"],"additionalProperties":false}},"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 placed this order"},"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","actor","createdAt","updatedAt"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `carrier_not_accepted`, `validation_error`, or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `carrier_not_accepted`, `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"]},"examples":{"example1":{"value":{"error":"carrier_not_accepted","message":"carrier is no longer accepted; we choose the carrier for you","requestId":"req-4f"}},"example2":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `parent_suspended`, `numbers_disabled`, `insufficient_key_permissions`, `spend_limit_exceeded`, or `parent_suspended`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `parent_suspended`, `numbers_disabled`, `insufficient_key_permissions`, `spend_limit_exceeded`, or `parent_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"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}},"example3":{"value":{"error":"numbers_disabled","message":"Numbers are not enabled for this account","requestId":"req-4f"}},"example4":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}},"example5":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","requestId":"req-4f"}},"example6":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}}}}}},"409":{"description":"The request conflicts with the current state. `error` is `coupon_used_up` or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `coupon_used_up` 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"]},"examples":{"example1":{"value":{"error":"coupon_used_up","message":"That coupon has been used up","requestId":"req-4f"}},"example2":{"value":{"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`, `country_not_offered`, `product_not_available`, `unknown_coupon`, `coupon_expired`, `coupon_not_applicable`, 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`, `country_not_offered`, `product_not_available`, `unknown_coupon`, `coupon_expired`, `coupon_not_applicable`, 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"]},"examples":{"example1":{"value":{"error":"no_offer","message":"No provider currently offers this combination","requestId":"req-4f"}},"example2":{"value":{"error":"service_required","message":"service is required for single_service numbers","requestId":"req-4f"}},"example3":{"value":{"error":"country_not_offered","message":"Numbers are not offered in this country yet","requestId":"req-4f"}},"example4":{"value":{"error":"product_not_available","message":"This number product is not available","requestId":"req-4f"}},"example5":{"value":{"error":"unknown_coupon","message":"That coupon code is not one we know","requestId":"req-4f"}},"example6":{"value":{"error":"coupon_expired","message":"That coupon is not running","requestId":"req-4f"}},"example7":{"value":{"error":"coupon_not_applicable","message":"That coupon does not apply to this order","requestId":"req-4f"}},"example8":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","createdAt"],"additionalProperties":false}},"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 placed this order"},"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","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","createdAt"],"additionalProperties":false}},"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 placed this order"},"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","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"},"in":"query","name":"endingSoon","required":false,"description":"`true` for active numbers with auto-renew off that stop within a day"},{"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `parent_suspended`, `numbers_disabled`, `insufficient_key_permissions`, `spend_limit_exceeded`, or `parent_suspended`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `parent_suspended`, `numbers_disabled`, `insufficient_key_permissions`, `spend_limit_exceeded`, or `parent_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"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}},"example3":{"value":{"error":"numbers_disabled","message":"Numbers are not enabled for this account","requestId":"req-4f"}},"example4":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}},"example5":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","requestId":"req-4f"}},"example6":{"value":{"error":"parent_suspended","message":"This account's parent 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"]},"examples":{"example1":{"value":{"error":"rental_not_active","message":"This number is expired","requestId":"req-4f"}},"example2":{"value":{"error":"rental_busy","message":"Another change to this number is in progress","requestId":"req-4f"}},"example3":{"value":{"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 `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"]},"examples":{"example1":{"value":{"error":"renewal_unavailable","message":"This number cannot be renewed for that length","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 before the number has received a message, and not before `cancellableFrom` while the provider still holds a new number (5 minutes for most).","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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `cancel_too_soon`, `rental_busy`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `not_cancellable`, `cancel_too_soon`, `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"]},"examples":{"example1":{"value":{"error":"not_cancellable","message":"This number has already received messages","requestId":"req-4f"}},"example2":{"value":{"error":"cancel_too_soon","message":"This number is too new to cancel; try again from cancellableFrom","requestId":"req-4f"}},"example3":{"value":{"error":"rental_busy","message":"Another change to this number is in progress","requestId":"req-4f"}},"example4":{"value":{"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 `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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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, promotions counted. 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"},{"schema":{"type":"string","minLength":1,"maxLength":40},"example":"LAUNCH25","in":"query","name":"coupon","required":false,"description":"Also count the promotion this coupon unlocks, as an order sending it would"}],"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"},"customerNormalPrice":{"examples":[1999],"description":"What the customer pays with no promotion, in `customerCurrency`. The same as `customerPrice` when no promotion applied. Only when you ask with `customerId`","anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}]},"customerPromotionEndsAt":{"description":"When the promotion behind `customerPrice` ends. Null when none applied. Only when you ask with `customerId`","anyOf":[{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"]},{"type":"null"}]},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `catalogue_loading`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `catalogue_loading`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"catalogue_loading","message":"The registrar's catalogue is still loading, retry shortly","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"]},"coupon":{"description":"Also count the promotion this coupon unlocks, as an order sending it would","type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"]}},"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"},"transferPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}],"examples":[null],"description":"What transferring this exact domain in would cost. Null when this ending cannot be transferred in"},"transferAddsYear":{"examples":[null],"description":"Whether completing the transfer adds a year to the registration. Null alongside `transferPrice`","type":["boolean","null"]},"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"},"customerNormalPrice":{"examples":[1999],"description":"What the customer pays with no promotion, in `customerCurrency`. The same as `customerPrice` when no promotion applied. Only when you ask with `customerId`","anyOf":[{"type":"integer","minimum":0,"examples":[1440],"description":"Minor units (US cents)"},{"type":"null"}]},"customerPromotionEndsAt":{"description":"When the promotion behind `customerPrice` ends. Null when none applied. Only when you ask with `customerId`","anyOf":[{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"]},{"type":"null"}]},"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","transferPrice","transferAddsYear","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `catalogue_loading`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `catalogue_loading`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"catalogue_loading","message":"The registrar's catalogue is still loading, retry shortly","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. A `coupon` is checked before the registrar is asked, so an order it cannot be used on is refused with nothing registered, unless you send `couponOptional`.","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, for this order alone. 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"]},"registrant":{"description":"Which stored contact to register to instead of a one-off `contact`: the named customer's own `registrant`, or your account's default registrant. Sending it with `contact` is refused, as is naming one that is not stored","type":"string","enum":["customer","default"]},"privacy":{"description":"Add WHOIS privacy. Absent, your account's default decides. An ending that does not offer privacy is refused","type":"boolean"},"coupon":{"description":"A coupon code, unlocking the promotion it belongs to for this registration. A promotion everyone on the list gets needs no code","type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"]},"couponOptional":{"default":false,"description":"Place the order at the normal price when the coupon cannot be used, instead of refusing it","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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"additionalProperties":false}}}},"400":{"description":"The request is malformed. `error` is `invalid_contact`, `validation_error`, or `invalid_idempotency_key`.","content":{"application/json":{"schema":{"description":"The request is malformed. `error` is `invalid_contact`, `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"]},"examples":{"example1":{"value":{"error":"invalid_contact","message":"contact.postalCode does not match the registry's format for this country","requestId":"req-4f"}},"example2":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}},"example4":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","requestId":"req-4f"}}}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_taken`, `domain_owned`, `coupon_used_up`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_taken`, `domain_owned`, `coupon_used_up`, 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"]},"examples":{"example1":{"value":{"error":"domain_taken","message":"This domain is already registered","requestId":"req-4f"}},"example2":{"value":{"error":"domain_owned","message":"You already have this domain","requestId":"req-4f"}},"example3":{"value":{"error":"coupon_used_up","message":"That coupon has been used up","requestId":"req-4f"}},"example4":{"value":{"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 `unsupported_tld`, `premium_domain`, `not_available`, `registrant_required`, `unsupported_period`, `privacy_unavailable`, `unknown_coupon`, `coupon_expired`, `coupon_not_applicable`, 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`, `unknown_coupon`, `coupon_expired`, `coupon_not_applicable`, 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"]},"examples":{"example1":{"value":{"error":"unsupported_tld","message":"This ending is not on offer","requestId":"req-4f"}},"example2":{"value":{"error":"premium_domain","message":"Premium domain names cannot be bought here yet","requestId":"req-4f"}},"example3":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example4":{"value":{"error":"registrant_required","message":"Set a registrant on this customer or a default one in your account settings, or send one with this order","requestId":"req-4f"}},"example5":{"value":{"error":"unsupported_period","message":"This ending can only be registered for 2 or 3 years","requestId":"req-4f"}},"example6":{"value":{"error":"privacy_unavailable","message":"This ending does not offer WHOIS privacy","requestId":"req-4f"}},"example7":{"value":{"error":"unknown_coupon","message":"That coupon code is not one we know","requestId":"req-4f"}},"example8":{"value":{"error":"coupon_expired","message":"That coupon is not running","requestId":"req-4f"}},"example9":{"value":{"error":"coupon_not_applicable","message":"That coupon does not apply to this order","requestId":"req-4f"}},"example10":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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`, `registrar_check_failed`, or `catalogue_loading`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `check_failed`, `registrar_check_failed`, or `catalogue_loading`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"check_failed","message":"The registrar could not take this order; nothing was charged","requestId":"req-4f"}},"example2":{"value":{"error":"registrar_check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}},"example3":{"value":{"error":"catalogue_loading","message":"The registrar's catalogue is still loading, retry shortly","requestId":"req-4f"}}}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_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"},"details":{"type":"object","description":"Present when `error` is `registrar_unavailable`, carrying `retryAfterSeconds`.","properties":{"retryAfterSeconds":{"type":"number","description":"Seconds to wait before retrying"}}}},"required":["error","message","requestId"]},"example":{"error":"registrar_unavailable","message":"The registrar is unavailable; nothing was charged","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"},"in":"query","name":"autoRenew","required":false,"description":"`true` or `false`"},{"schema":{"type":"string"},"in":"query","name":"expiringSoon","required":false,"description":"`true` for active domains expiring within 30 days"},{"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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/renewal-forecast":{"get":{"operationId":"getDomainRenewalForecast","summary":"Forecast upcoming auto-renewals","tags":["Domains"],"description":"What auto-renew will charge your wallet over the next 30 days: every domain with it on, due to renew inside that window, added up.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"amount":{"type":"integer","minimum":0,"examples":[1440],"description":"What auto-renew will charge in total, in minor units"},"count":{"type":"integer","description":"How many domains that covers"}},"required":["amount","count"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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, charging for privacy turned on","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. Only privacy costs anything: turning it on charges your wallet for the whole years left in the current term, and turning it off refunds nothing. 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, which the domain must already have or this same request must set","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. Turning it on charges the whole years left in the current term at the price for this ending, and every renewal from then on charges it by the year; turning it off refunds nothing. Privacy already where you are asking for it is charged 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"}]},"autoRenew":{"description":"Renew this domain from your wallet shortly before it expires. Local to your account: nothing is charged by turning it on or off, and nothing reaches the registrar","type":"boolean"},"releaseHostedDns":{"description":"Switch hosted DNS off as part of this change. Without it, changing the nameservers of a domain whose DNS we host is refused: the registrar deletes the unused zone after 7 days and the records stored here go with it","type":"boolean"},"acknowledgeMailboxes":{"description":"Change the nameservers of a domain connected for mailboxes anyway. Without it, moving them off its mailboxes' own is refused: mail on it stops once they no longer resolve there","type":"boolean"}}}}}},"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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `parent_suspended`, or `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `parent_suspended`, or `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `registrar_refused`, `dns_hosted`, `dns_not_supported`, `nameservers_used_by_mailboxes`, `branded_nameservers_in_use`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `domain_busy`, `registrar_refused`, `dns_hosted`, `dns_not_supported`, `nameservers_used_by_mailboxes`, `branded_nameservers_in_use`, 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"},"details":{"type":"object","description":"Present when `error` is `branded_nameservers_in_use`, carrying `names`.","properties":{"names":{"type":"array","description":"The branded nameserver set this domain carries"}}}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"domain_busy","message":"Another renewal of this domain is in progress","requestId":"req-4f"}},"example3":{"value":{"error":"registrar_refused","message":"The registrar refused this change to the domain","requestId":"req-4f"}},"example4":{"value":{"error":"dns_hosted","message":"Hosted DNS is on for this domain","requestId":"req-4f"}},"example5":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example6":{"value":{"error":"nameservers_used_by_mailboxes","message":"example.com has 3 Google mailboxes. Changing nameservers stops their mail.","requestId":"req-4f"}},"example7":{"value":{"error":"branded_nameservers_in_use","message":"This domain carries your branded nameserver set; remove it before doing this","requestId":"req-4f"}},"example8":{"value":{"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 `invalid_nameserver`, `not_available`, `privacy_unavailable`, `registrant_required`, `sub_reseller_feature_unavailable`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_nameserver`, `not_available`, `privacy_unavailable`, `registrant_required`, `sub_reseller_feature_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"]},"examples":{"example1":{"value":{"error":"invalid_nameserver","message":"Each nameserver must be a hostname, like ns1.example.com","requestId":"req-4f"}},"example2":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example3":{"value":{"error":"privacy_unavailable","message":"This ending does not offer WHOIS privacy","requestId":"req-4f"}},"example4":{"value":{"error":"registrant_required","message":"Set a registrant on this customer or a default one in your account settings, or send one with this order","requestId":"req-4f"}},"example5":{"value":{"error":"sub_reseller_feature_unavailable","message":"A sub-reseller cannot transfer a domain in yet","requestId":"req-4f"}},"example6":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `registrar_check_failed`, `catalogue_loading`, or `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `registrar_check_failed`, `catalogue_loading`, or `dns_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"]},"examples":{"example1":{"value":{"error":"registrar_check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}},"example2":{"value":{"error":"catalogue_loading","message":"The registrar's catalogue is still loading, retry shortly","requestId":"req-4f"}},"example3":{"value":{"error":"dns_failed","message":"The registrar could not complete this DNS change","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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `branded_nameservers_in_use`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_not_deletable`, `domain_busy`, `branded_nameservers_in_use`, 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"},"details":{"type":"object","description":"Present when `error` is `branded_nameservers_in_use`, carrying `names`.","properties":{"names":{"type":"array","description":"The branded nameserver set this domain carries"}}}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_not_deletable","message":"This domain cannot be deleted as it stands","requestId":"req-4f"}},"example2":{"value":{"error":"domain_busy","message":"Another renewal of this domain is in progress","requestId":"req-4f"}},"example3":{"value":{"error":"branded_nameservers_in_use","message":"This domain carries your branded nameserver set; remove it before doing this","requestId":"req-4f"}},"example4":{"value":{"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 `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"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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. A promotion only reaches a renewal when it is set to; an introductory offer the domain was first bought on does not.","requestBody":{"required":true,"content":{"application/json":{"schema":{"default":{"couponOptional":false},"type":"object","properties":{"years":{"description":"How many years. Defaults to 1","type":"integer","minimum":1,"maximum":10},"coupon":{"description":"A coupon code, unlocking the promotion it belongs to for this renewal","type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"]},"couponOptional":{"default":false,"description":"Place the order at the normal price when the coupon cannot be used, instead of refusing it","type":"boolean"}}}}}},"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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}},"example4":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","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 `coupon_used_up`, `domain_busy`, `domain_expired`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `coupon_used_up`, `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"]},"examples":{"example1":{"value":{"error":"coupon_used_up","message":"That coupon has been used up","requestId":"req-4f"}},"example2":{"value":{"error":"domain_busy","message":"Another renewal of this domain is in progress","requestId":"req-4f"}},"example3":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example4":{"value":{"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_coupon`, `coupon_expired`, `coupon_not_applicable`, `not_available`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `unknown_coupon`, `coupon_expired`, `coupon_not_applicable`, `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"]},"examples":{"example1":{"value":{"error":"unknown_coupon","message":"That coupon code is not one we know","requestId":"req-4f"}},"example2":{"value":{"error":"coupon_expired","message":"That coupon is not running","requestId":"req-4f"}},"example3":{"value":{"error":"coupon_not_applicable","message":"That coupon does not apply to this order","requestId":"req-4f"}},"example4":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example5":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_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"},"details":{"type":"object","description":"Present when `error` is `registrar_unavailable`, carrying `retryAfterSeconds`.","properties":{"retryAfterSeconds":{"type":"number","description":"Seconds to wait before retrying"}}}},"required":["error","message","requestId"]},"example":{"error":"registrar_unavailable","message":"The registrar is unavailable; nothing was charged","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `domain_expired`, or `branded_nameservers_in_use`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_locked`, `domain_expired`, or `branded_nameservers_in_use`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"},"details":{"type":"object","description":"Present when `error` is `branded_nameservers_in_use`, carrying `names`.","properties":{"names":{"type":"array","description":"The branded nameserver set this domain carries"}}}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_locked","message":"Turn the transfer lock off before asking for a transfer code","requestId":"req-4f"}},"example2":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example3":{"value":{"error":"branded_nameservers_in_use","message":"This domain carries your branded nameserver set; remove it before doing this","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/resend-validation":{"post":{"operationId":"resendDomainValidation","summary":"Resend the registrant validation email","tags":["Domains"],"description":"For a domain stuck in `pending_validation`: asks the registrar to send the registrant another copy of the validation email. Only the registrant's own link in that email can clear the hold; this never changes the domain itself.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"204":{"description":"Sent"},"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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_pending_validation`, `resend_validation_unsupported`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_pending_validation`, `resend_validation_unsupported`, or `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"]},"examples":{"example1":{"value":{"error":"not_pending_validation","message":"This domain is not waiting on registrant validation","requestId":"req-4f"}},"example2":{"value":{"error":"resend_validation_unsupported","message":"This registrar has no way to resend the validation email","requestId":"req-4f"}},"example3":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `resend_validation_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `resend_validation_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":"resend_validation_failed","message":"The registrar could not resend the validation email","requestId":"req-4f"}}}}}}},"/v1/domains/transfers":{"post":{"operationId":"transferDomain","summary":"Transfer a domain in","tags":["Domain transfers"],"description":"Starts a transfer in from another registrar: holds the transfer price for this ending and answers 202 with a transfer whose status you poll. A wrong auth code is never known this early - only the losing registrar or the registrant finds that out, which can take days - so it never fails this call; it only ever shows up later as this transfer ending `rejected`. Send an Idempotency-Key header so a retry can never start a second one.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253,"examples":["northwind-telecom.com"]},"authCode":{"type":"string","minLength":1,"maxLength":64,"description":"The code the losing registrar issued, often called the auth or EPP code"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"Required: every purchase belongs to one of your customers"}},"required":["domain","authCode","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":{"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":["dtx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","completed","rejected","cancelled","failed"]},"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":"What the transfer itself costs, in minor units"},"addsYear":{"type":"boolean","description":"Whether completing this transfer adds a year to the registration"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"0 until the transfer completes, then `unitPrice`"},"subState":{"description":"A plain-English sentence about the registrar’s own finer sub-state while `pending` - waiting for the registry, the losing registrar or the registrant’s own approval. Null once it is no longer pending","type":["string","null"]},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain this created once it completed. Null until then"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When it finished, whichever way. Null while pending"}},"required":["id","domain","status","customerId","unitPrice","addsYear","paidTotal","subState","domainId","createdAt","resolvedAt"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}},"example4":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","requestId":"req-4f"}}}}}},"409":{"description":"The request conflicts with the current state. `error` is `domain_owned`, `transfer_in_progress`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_owned`, `transfer_in_progress`, 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"]},"examples":{"example1":{"value":{"error":"domain_owned","message":"You already have this domain","requestId":"req-4f"}},"example2":{"value":{"error":"transfer_in_progress","message":"A transfer for this domain is already in progress","requestId":"req-4f"}},"example3":{"value":{"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 `unsupported_tld`, `registrant_required`, `not_available`, `sub_reseller_feature_unavailable`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `unsupported_tld`, `registrant_required`, `not_available`, `sub_reseller_feature_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"]},"examples":{"example1":{"value":{"error":"unsupported_tld","message":"This ending is not on offer","requestId":"req-4f"}},"example2":{"value":{"error":"registrant_required","message":"Set a registrant on this customer or a default one in your account settings, or send one with this order","requestId":"req-4f"}},"example3":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example4":{"value":{"error":"sub_reseller_feature_unavailable","message":"A sub-reseller cannot transfer a domain in yet","requestId":"req-4f"}},"example5":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `registrar_check_failed` or `catalogue_loading`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `registrar_check_failed` or `catalogue_loading`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"registrar_check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}},"example2":{"value":{"error":"catalogue_loading","message":"The registrar's catalogue is still loading, retry shortly","requestId":"req-4f"}}}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_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"},"details":{"type":"object","description":"Present when `error` is `registrar_unavailable`, carrying `retryAfterSeconds`.","properties":{"retryAfterSeconds":{"type":"number","description":"Seconds to wait before retrying"}}}},"required":["error","message","requestId"]},"example":{"error":"registrar_unavailable","message":"The registrar is unavailable; nothing was charged","requestId":"req-4f"}}}}}},"get":{"operationId":"listDomainTransfers","summary":"List domain transfers","tags":["Domain transfers"],"description":"Transfers in you have started, newest first.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["dtx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","completed","rejected","cancelled","failed"]},"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":"What the transfer itself costs, in minor units"},"addsYear":{"type":"boolean","description":"Whether completing this transfer adds a year to the registration"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"0 until the transfer completes, then `unitPrice`"},"subState":{"description":"A plain-English sentence about the registrar’s own finer sub-state while `pending` - waiting for the registry, the losing registrar or the registrant’s own approval. Null once it is no longer pending","type":["string","null"]},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain this created once it completed. Null until then"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When it finished, whichever way. Null while pending"}},"required":["id","domain","status","customerId","unitPrice","addsYear","paidTotal","subState","domainId","createdAt","resolvedAt"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/transfers/{id}":{"delete":{"operationId":"cancelDomainTransfer","summary":"Cancel a domain transfer","tags":["Domain transfers"],"description":"Cancels a transfer that is still pending and gives the hold back in full.","parameters":[{"schema":{"type":"string"},"example":"dtx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["dtx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-telecom.com"]},"status":{"type":"string","enum":["pending","completed","rejected","cancelled","failed"]},"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":"What the transfer itself costs, in minor units"},"addsYear":{"type":"boolean","description":"Whether completing this transfer adds a year to the registration"},"paidTotal":{"type":"integer","minimum":0,"examples":[1440],"description":"0 until the transfer completes, then `unitPrice`"},"subState":{"description":"A plain-English sentence about the registrar’s own finer sub-state while `pending` - waiting for the registry, the losing registrar or the registrant’s own approval. Null once it is no longer pending","type":["string","null"]},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain this created once it completed. Null until then"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"resolvedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When it finished, whichever way. Null while pending"}},"required":["id","domain","status","customerId","unitPrice","addsYear","paidTotal","subState","domainId","createdAt","resolvedAt"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `transfer_not_pending`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `transfer_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":"transfer_not_pending","message":"This transfer has already been resolved","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `registrar_check_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `registrar_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":"registrar_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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `parent_suspended`, `insufficient_key_permissions`, or `spend_limit_exceeded`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"parent_suspended","message":"This account's parent is suspended","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}},"example4":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","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"]},"examples":{"example1":{"value":{"error":"domain_busy","message":"Another renewal of this domain is in progress","requestId":"req-4f"}},"example2":{"value":{"error":"domain_not_in_redemption","message":"Only a domain in redemption can be restored","requestId":"req-4f"}},"example3":{"value":{"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 `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"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `registrar_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"},"details":{"type":"object","description":"Present when `error` is `registrar_unavailable`, carrying `retryAfterSeconds`.","properties":{"retryAfterSeconds":{"type":"number","description":"Seconds to wait before retrying"}}}},"required":["error","message","requestId"]},"example":{"error":"registrar_unavailable","message":"The registrar is unavailable; nothing was charged","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `registrar_check_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `registrar_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":"registrar_check_failed","message":"The registrar could not be reached to check this domain","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/hosts":{"get":{"operationId":"listDomainHosts","summary":"List a domain's hosts","tags":["Child nameservers"],"description":"The child nameservers (glue records) registered at the registrar under this domain, such as ns1.acme.com for acme.com, each with the addresses it answers on. Hosts live at the registrar, not on this record, so this always reads them fresh.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"A domain's hosts","content":{"application/json":{"schema":{"description":"A domain's hosts","type":"object","properties":{"hosts":{"type":"array","items":{"type":"object","properties":{"host":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"],"description":"The host name, a hostname under the domain, like ns1.acme.com"},"addresses":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":45,"examples":["203.0.113.10"],"description":"An IPv4 or IPv6 address"},"description":"1 to 10 addresses this host answers on"}},"required":["host","addresses"],"additionalProperties":false,"description":"A host (child nameserver / glue record) registered at the registrar"},"description":"Every host registered under this domain"}},"required":["hosts"],"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_expired`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `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_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 `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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `host_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `host_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":"host_failed","message":"The registrar could not complete this host change","requestId":"req-4f"}}}}}},"post":{"operationId":"createDomainHost","summary":"Register a child nameserver","tags":["Child nameservers"],"description":"Registers a host (glue record) at the registrar, such as ns1.acme.com for acme.com, with the addresses it answers on. The host must be a hostname under this exact domain.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"],"description":"The host name, under this domain, like ns1.acme.com"},"addresses":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":45,"examples":["203.0.113.10"],"description":"An IPv4 or IPv6 address"},"description":"1 to 10 addresses this host answers on"}},"required":["host","addresses"]}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"201":{"description":"A host (child nameserver / glue record) registered at the registrar","content":{"application/json":{"schema":{"description":"A host (child nameserver / glue record) registered at the registrar","type":"object","properties":{"host":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"],"description":"The host name, a hostname under the domain, like ns1.acme.com"},"addresses":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":45,"examples":["203.0.113.10"],"description":"An IPv4 or IPv6 address"},"description":"1 to 10 addresses this host answers on"}},"required":["host","addresses"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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` or `registrar_refused`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired` 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"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"registrar_refused","message":"The registrar refused this change to the domain","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `host_not_under_domain`, or `invalid_host_address`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `host_not_under_domain`, or `invalid_host_address`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"host_not_under_domain","message":"The host must be a hostname under this exact domain","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_host_address","message":"Give 1 to 10 unique IPv4 or IPv6 addresses, each a valid one","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `host_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `host_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":"host_failed","message":"The registrar could not complete this host change","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/hosts/{host}":{"patch":{"operationId":"updateDomainHost","summary":"Change a host's addresses","tags":["Child nameservers"],"description":"Replaces a host's full address list at the registrar. There is no rename: to change the name itself, delete this host and create one under the new name.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"addresses":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":45,"examples":["203.0.113.10"],"description":"An IPv4 or IPv6 address"},"description":"1 to 10 addresses this host answers on"}},"required":["addresses"]}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":4,"maxLength":253},"example":"ns1.example-dns.com","in":"path","name":"host","required":true,"description":"The host name"}],"responses":{"200":{"description":"A host (child nameserver / glue record) registered at the registrar","content":{"application/json":{"schema":{"description":"A host (child nameserver / glue record) registered at the registrar","type":"object","properties":{"host":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"],"description":"The host name, a hostname under the domain, like ns1.acme.com"},"addresses":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":2,"maxLength":45,"examples":["203.0.113.10"],"description":"An IPv4 or IPv6 address"},"description":"1 to 10 addresses this host answers on"}},"required":["host","addresses"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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` or `registrar_refused`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired` 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"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"registrar_refused","message":"The registrar refused this change to the domain","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `host_not_under_domain`, or `invalid_host_address`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `host_not_under_domain`, or `invalid_host_address`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"host_not_under_domain","message":"The host must be a hostname under this exact domain","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_host_address","message":"Give 1 to 10 unique IPv4 or IPv6 addresses, each a valid one","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `host_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `host_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":"host_failed","message":"The registrar could not complete this host change","requestId":"req-4f"}}}}}},"delete":{"operationId":"deleteDomainHost","summary":"Delete a host","tags":["Child nameservers"],"description":"Deletes a host (glue record) at the registrar. Refused while any of your domains - including this one - still lists it as a nameserver.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":4,"maxLength":253},"example":"ns1.example-dns.com","in":"path","name":"host","required":true,"description":"The host name"}],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `host_in_use`, or `registrar_refused`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `host_in_use`, 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"},"details":{"type":"object","description":"Present when `error` is `host_in_use`, carrying `domain`.","properties":{"domain":{"type":"string","description":"The domain that still lists this host as a nameserver"}}}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"host_in_use","message":"This host is still listed as a nameserver on one of your domains","requestId":"req-4f"}},"example3":{"value":{"error":"registrar_refused","message":"The registrar refused this change to the domain","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `host_not_under_domain`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available` or `host_not_under_domain`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"host_not_under_domain","message":"The host must be a hostname under this exact domain","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `host_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `host_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":"host_failed","message":"The registrar could not complete this host change","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","enum":["domain.registered","domain.renewed","domain.renewal_pending","domain.registration_failed","domain.renewal_failed","domain.expiring","domain.needs_attention","domain.expired","domain.updated","domain.host_created","domain.host_updated","domain.host_deleted","domain.auth_code_generated","domain.transferred_out","domain.transfer.completed","domain.transfer.failed","domain.restored","domain.restore_failed","domain.deleted","domain.suspended","domain.unsuspended"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/dns":{"put":{"operationId":"setDomainDns","summary":"Turn hosted DNS, or DNSSEC on a hosted zone, on or off","tags":["DNS"],"description":"Hosts this domain's DNS with us, or hands it back. Turning it on creates the zone at the registrar and points the domain at the registrar's DNS nameservers, keeping the ones it had so turning it off can put them back. Turning it off puts the domain on the nameservers you send, or the ones it had before hosting, or the registrar's own - and gives the zone up: the records stored here go with it, and so does any DNSSEC signing. Hosted DNS is included with the domain and costs nothing. Asking for the state it is already in changes nothing. `dnssec` signs or unsigns a zone already hosted with us: we manage the keys and any rollover, and only on or off is ever asked for. Give `hosted`, `dnssec`, or both.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hosted":{"description":"True hosts the zone with us; false hands DNS back","type":"boolean"},"nameservers":{"description":"Where to point the domain when turning hosting off. Left out, it goes back to the nameservers it had before hosting, or the registrar's own","minItems":2,"maxItems":6,"type":"array","items":{"type":"string","minLength":4,"maxLength":253,"examples":["ns1.example-dns.com"]}},"dnssec":{"description":"Signs or unsigns a zone already hosted with us","type":"boolean"}}}}}},"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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `dnssec_not_available`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `dnssec_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"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","requestId":"req-4f"}},"example4":{"value":{"error":"dns_busy","message":"Another change to this zone is in progress","requestId":"req-4f"}},"example5":{"value":{"error":"dnssec_not_available","message":"DNSSEC isn't available for a domain whose DNS is hosted with its mailboxes","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_nameserver`, or `dnssec_unavailable`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_nameserver`, or `dnssec_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"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_nameserver","message":"Each nameserver must be a hostname, like ns1.example.com","requestId":"req-4f"}},"example3":{"value":{"error":"dnssec_unavailable","message":"This ending does not support DNSSEC","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/dnssec":{"put":{"operationId":"setDomainDnssecKeys","summary":"Set the DNSSEC keys for a domain hosted elsewhere","tags":["DNS"],"description":"Sends the DNSSEC keys your own DNS provider generated, so the registry can add the matching DS record. An empty list removes every key and, with it, every DS record the registry holds - the only way one is ever removed. Refused when this domain's DNS is hosted with us: turn signing on or off with `PUT /v1/domains/{id}/dns` instead, since we manage those keys.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"maxItems":4,"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"Every key to send, up to 4. Empty removes every key"}},"required":["keys"]}}}},"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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_hosted`, or `dnssec_not_available`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_hosted`, or `dnssec_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"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_hosted","message":"Hosted DNS is on for this domain","requestId":"req-4f"}},"example3":{"value":{"error":"dnssec_not_available","message":"DNSSEC isn't available for a domain whose DNS is hosted with its mailboxes","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `dnssec_unavailable`, `too_many_dnssec_keys`, or `invalid_dnssec_key`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `dnssec_unavailable`, `too_many_dnssec_keys`, or `invalid_dnssec_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"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"dnssec_unavailable","message":"This ending does not support DNSSEC","requestId":"req-4f"}},"example3":{"value":{"error":"too_many_dnssec_keys","message":"At most 4 keys are allowed","requestId":"req-4f"}},"example4":{"value":{"error":"invalid_dnssec_key","message":"Key 1: flags must be 256 or 257","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/dns/records":{"get":{"operationId":"listDomainDnsRecords","summary":"List a zone's records","tags":["DNS"],"description":"Every record in the zone we host for this domain, each with an id you can change or delete it by. Hosted DNS has to be on first.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"A hosted zone's records","content":{"application/json":{"schema":{"description":"A hosted zone's records","type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS","URL","MBOXFW"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation URL and MBOXFW are set only by forwarding (`PUT /domains/{id}/forwarding`, `PUT /domains/{id}/email-forwarding`) and read-only here"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"anyOf":[{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"},{"type":"null"}],"examples":[null],"description":"The priority, or null on a type that has none. Always there"},"managedBy":{"anyOf":[{"type":"string","enum":["url_forwarding","email_forwarding"]},{"type":"null"}],"examples":[null],"description":"Set when a forwarding feature made this record; change it from the forwarding settings instead of the generic record routes, which refuse it. Null otherwise"}},"required":["id","name","type","content","ttl","priority","managedBy"],"additionalProperties":false,"description":"One record in the zone we host for this domain"},"description":"Every record in the zone"}},"required":["records"],"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_expired`, `dns_not_supported`, or `dns_not_hosted`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, or `dns_not_hosted`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"createDomainDnsRecord","summary":"Add a record","tags":["DNS"],"description":"Adds one record to the zone. The record is checked here before the registrar sees any of it: a CNAME at the root or beside another record with the same name, a missing MX priority and a malformed address are each refused with a message naming the record, and nothing is sent upstream.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"}},"required":["name","type","content"]}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"201":{"description":"One record in the zone we host for this domain","content":{"application/json":{"schema":{"description":"One record in the zone we host for this domain","type":"object","properties":{"id":{"type":"string","examples":["dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS","URL","MBOXFW"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation URL and MBOXFW are set only by forwarding (`PUT /domains/{id}/forwarding`, `PUT /domains/{id}/email-forwarding`) and read-only here"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"anyOf":[{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"},{"type":"null"}],"examples":[null],"description":"The priority, or null on a type that has none. Always there"},"managedBy":{"anyOf":[{"type":"string","enum":["url_forwarding","email_forwarding"]},{"type":"null"}],"examples":[null],"description":"Set when a forwarding feature made this record; change it from the forwarding settings instead of the generic record routes, which refuse it. Null otherwise"}},"required":["id","name","type","content","ttl","priority","managedBy"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_not_supported`, `dns_not_hosted`, or `dns_busy`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, `dns_not_hosted`, or `dns_busy`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","requestId":"req-4f"}},"example4":{"value":{"error":"dns_busy","message":"Another change to this zone is in progress","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_dns_record`, `dns_record_conflict`, or `too_many_dns_records`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_dns_record`, `dns_record_conflict`, or `too_many_dns_records`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_dns_record","message":"Check the record name, type, content and TTL","requestId":"req-4f"}},"example3":{"value":{"error":"dns_record_conflict","message":"A CNAME cannot sit beside another record with the same name","requestId":"req-4f"}},"example4":{"value":{"error":"too_many_dns_records","message":"A zone holds at most 200 records","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}},"put":{"operationId":"replaceDomainDnsRecords","summary":"Replace every record","tags":["DNS"],"description":"Swaps the whole record set in one call, for keeping DNS in a system of your own. At most 200 records. Every record is checked first, so one bad record leaves the zone exactly as it was. The ids are new: these are new records, not edits of the ones they replace.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"maxItems":200,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"}},"required":["name","type","content"]},"description":"The full new set. An empty list empties the zone"}},"required":["records"]}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"A hosted zone's records","content":{"application/json":{"schema":{"description":"A hosted zone's records","type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS","URL","MBOXFW"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation URL and MBOXFW are set only by forwarding (`PUT /domains/{id}/forwarding`, `PUT /domains/{id}/email-forwarding`) and read-only here"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"anyOf":[{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"},{"type":"null"}],"examples":[null],"description":"The priority, or null on a type that has none. Always there"},"managedBy":{"anyOf":[{"type":"string","enum":["url_forwarding","email_forwarding"]},{"type":"null"}],"examples":[null],"description":"Set when a forwarding feature made this record; change it from the forwarding settings instead of the generic record routes, which refuse it. Null otherwise"}},"required":["id","name","type","content","ttl","priority","managedBy"],"additionalProperties":false,"description":"One record in the zone we host for this domain"},"description":"Every record in the zone"}},"required":["records"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_not_supported`, `dns_not_hosted`, or `dns_busy`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, `dns_not_hosted`, or `dns_busy`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","requestId":"req-4f"}},"example4":{"value":{"error":"dns_busy","message":"Another change to this zone is in progress","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_dns_record`, `dns_record_conflict`, or `too_many_dns_records`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_dns_record`, `dns_record_conflict`, or `too_many_dns_records`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_dns_record","message":"Check the record name, type, content and TTL","requestId":"req-4f"}},"example3":{"value":{"error":"dns_record_conflict","message":"A CNAME cannot sit beside another record with the same name","requestId":"req-4f"}},"example4":{"value":{"error":"too_many_dns_records","message":"A zone holds at most 200 records","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/dns/records/{recordId}":{"patch":{"operationId":"updateDomainDnsRecord","summary":"Change a record","tags":["DNS"],"description":"Changes one record. Send only the fields you want to change. Changing the type to one that has no priority drops the priority with it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"}}}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string"},"example":"dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"recordId","required":true}],"responses":{"200":{"description":"One record in the zone we host for this domain","content":{"application/json":{"schema":{"description":"One record in the zone we host for this domain","type":"object","properties":{"id":{"type":"string","examples":["dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS","URL","MBOXFW"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation URL and MBOXFW are set only by forwarding (`PUT /domains/{id}/forwarding`, `PUT /domains/{id}/email-forwarding`) and read-only here"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"anyOf":[{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"},{"type":"null"}],"examples":[null],"description":"The priority, or null on a type that has none. Always there"},"managedBy":{"anyOf":[{"type":"string","enum":["url_forwarding","email_forwarding"]},{"type":"null"}],"examples":[null],"description":"Set when a forwarding feature made this record; change it from the forwarding settings instead of the generic record routes, which refuse it. Null otherwise"}},"required":["id","name","type","content","ttl","priority","managedBy"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `dns_record_managed`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `dns_record_managed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","requestId":"req-4f"}},"example4":{"value":{"error":"dns_busy","message":"Another change to this zone is in progress","requestId":"req-4f"}},"example5":{"value":{"error":"dns_record_managed","message":"This record is managed by forwarding","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_dns_record`, `dns_record_conflict`, or `too_many_dns_records`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_dns_record`, `dns_record_conflict`, or `too_many_dns_records`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_dns_record","message":"Check the record name, type, content and TTL","requestId":"req-4f"}},"example3":{"value":{"error":"dns_record_conflict","message":"A CNAME cannot sit beside another record with the same name","requestId":"req-4f"}},"example4":{"value":{"error":"too_many_dns_records","message":"A zone holds at most 200 records","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}},"delete":{"operationId":"deleteDomainDnsRecord","summary":"Delete a record","tags":["DNS"],"description":"Removes one record from the zone. The rest of the zone is sent to the registrar as it now stands, because a zone is replaced whole.","parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string"},"example":"dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"recordId","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `dns_record_managed`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `dns_record_managed`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","requestId":"req-4f"}},"example4":{"value":{"error":"dns_busy","message":"Another change to this zone is in progress","requestId":"req-4f"}},"example5":{"value":{"error":"dns_record_managed","message":"This record is managed by forwarding","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/forwarding":{"put":{"operationId":"setDomainForwarding","summary":"Set URL forwarding","tags":["DNS"],"description":"Redirects the root, and any named subdomains, to a destination URL - a permanent (301) redirect, the only kind the registrar behind hosted DNS does. Replaces only the records this made before: anything you added by hand is untouched. An empty list removes forwarding. Hosted DNS has to be on first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"subdomain":{"description":"Empty/omitted means the root","type":"string"},"target":{"type":"string","examples":["https://example.com"],"description":"Where to redirect to: an absolute http or https URL"}},"required":["target"]},"description":"The full new set. An empty list removes forwarding"}},"required":["records"]}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"A hosted zone's records","content":{"application/json":{"schema":{"description":"A hosted zone's records","type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS","URL","MBOXFW"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation URL and MBOXFW are set only by forwarding (`PUT /domains/{id}/forwarding`, `PUT /domains/{id}/email-forwarding`) and read-only here"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"anyOf":[{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"},{"type":"null"}],"examples":[null],"description":"The priority, or null on a type that has none. Always there"},"managedBy":{"anyOf":[{"type":"string","enum":["url_forwarding","email_forwarding"]},{"type":"null"}],"examples":[null],"description":"Set when a forwarding feature made this record; change it from the forwarding settings instead of the generic record routes, which refuse it. Null otherwise"}},"required":["id","name","type","content","ttl","priority","managedBy"],"additionalProperties":false,"description":"One record in the zone we host for this domain"},"description":"Every record in the zone"}},"required":["records"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `forwarding_not_available`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `forwarding_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"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","requestId":"req-4f"}},"example4":{"value":{"error":"dns_busy","message":"Another change to this zone is in progress","requestId":"req-4f"}},"example5":{"value":{"error":"forwarding_not_available","message":"Forwarding isn't available for a domain whose DNS is hosted with its mailboxes","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_forward_url`, or `too_many_dns_records`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_forward_url`, or `too_many_dns_records`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_forward_url","message":"The destination must be an http or https URL","requestId":"req-4f"}},"example3":{"value":{"error":"too_many_dns_records","message":"A zone holds at most 200 records","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}}},"/v1/domains/{id}/email-forwarding":{"put":{"operationId":"setDomainEmailForwarding","summary":"Set email forwarding","tags":["DNS"],"description":"Forwards mail for a named address, or the catch-all, to another address. Replaces only the records this made before: anything you added by hand is untouched. An empty list removes forwarding. Hosted DNS has to be on first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"address":{"description":"Empty, or '*', means catch-all","type":"string"},"target":{"type":"string","format":"email","description":"The address to forward to"}},"required":["target"]},"description":"The full new set. An empty list removes forwarding"}},"required":["records"]}}}},"parameters":[{"schema":{"type":"string"},"example":"dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"A hosted zone's records","content":{"application/json":{"schema":{"description":"A hosted zone's records","type":"object","properties":{"records":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["dns_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","minLength":1,"maxLength":253,"examples":["www.acme.com"],"description":"The record name. `@` and the domain itself both mean the root; a bare label like `www` is taken as being under the domain. Stored and returned absolute and lower case"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA","NS","ALIAS","URL","MBOXFW"],"examples":["A"],"description":"A and AAAA point at an IPv4 or IPv6 address. CNAME points a name at another name, and cannot sit at the root or beside any other record with the same name - use ALIAS at the root. MX needs a priority and points at a mail host. TXT holds free text, SRV a service at `weight port target`, CAA a `flag tag \"value\"` certificate rule, NS a delegation URL and MBOXFW are set only by forwarding (`PUT /domains/{id}/forwarding`, `PUT /domains/{id}/email-forwarding`) and read-only here"},"content":{"type":"string","minLength":1,"maxLength":4096,"examples":["203.0.113.10"],"description":"What the record answers with, in the form its type takes"},"ttl":{"type":"integer","minimum":60,"maximum":604800,"examples":[3600],"description":"How long resolvers may cache it, in seconds, from 60. Defaults to 3600"},"priority":{"anyOf":[{"type":"integer","minimum":0,"maximum":65535,"examples":[10],"description":"Lower is tried first. Required on MX and SRV, and refused on every other type"},{"type":"null"}],"examples":[null],"description":"The priority, or null on a type that has none. Always there"},"managedBy":{"anyOf":[{"type":"string","enum":["url_forwarding","email_forwarding"]},{"type":"null"}],"examples":[null],"description":"Set when a forwarding feature made this record; change it from the forwarding settings instead of the generic record routes, which refuse it. Null otherwise"}},"required":["id","name","type","content","ttl","priority","managedBy"],"additionalProperties":false,"description":"One record in the zone we host for this domain"},"description":"Every record in the zone"}},"required":["records"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `forwarding_not_available`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `domain_expired`, `dns_not_supported`, `dns_not_hosted`, `dns_busy`, or `forwarding_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"]},"examples":{"example1":{"value":{"error":"domain_expired","message":"Renew this domain before changing it","requestId":"req-4f"}},"example2":{"value":{"error":"dns_not_supported","message":"This registrar does not host DNS","requestId":"req-4f"}},"example3":{"value":{"error":"dns_not_hosted","message":"Turn hosted DNS on for this domain first","requestId":"req-4f"}},"example4":{"value":{"error":"dns_busy","message":"Another change to this zone is in progress","requestId":"req-4f"}},"example5":{"value":{"error":"forwarding_not_available","message":"Forwarding isn't available for a domain whose DNS is hosted with its mailboxes","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_forward_address`, or `too_many_dns_records`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_forward_address`, or `too_many_dns_records`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_forward_address","message":"The destination must be an email address","requestId":"req-4f"}},"example3":{"value":{"error":"too_many_dns_records","message":"A zone holds at most 200 records","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 `dns_failed`.","content":{"application/json":{"schema":{"description":"The upstream provider failed. Nothing was charged. `error` is `dns_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":"dns_failed","message":"The registrar could not complete this DNS change","requestId":"req-4f"}}}}}}},"/v1/mailboxes/price":{"get":{"operationId":"getMailboxPrice","summary":"Get the mailbox price","tags":["Mailboxes"],"description":"What one Google mailbox costs you per month today. A domain keeps the price it was connected at. Each domain takes up to 10 mailboxes.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"price":{"type":"integer","minimum":0,"examples":[450],"description":"Per mailbox per month"},"perDomain":{"type":"integer","examples":[10]}},"required":["price","perDomain"],"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"}}}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailboxes":{"post":{"operationId":"createMailboxes","summary":"Order mailboxes","tags":["Mailboxes"],"description":"Orders Google mailboxes on a domain, by its name or id: the one call you need. A domain you bought here needs nothing else: we point its nameservers ourselves, keep its existing records (website, verifications), and the mailboxes are set up as soon as it is ready (`nameserversManaged: true`). For a domain registered elsewhere, set the `nameservers` in `mailboxDomain` at its registrar; the mailboxes wait, paid for, and are set up once it points there. A domain nobody has registered is checked with the registrar first: send `buy: true` to register it (a year, to the registrant on the customer or your account default) before its mailboxes are ordered, or leave it off and get `domain_not_registered`, with nothing held or charged. A premium name is never bought here, whatever `buy` says (`premium_domain`). Order more later the same way, up to 10 per domain. Each month is held from your wallet now (checked first, so a short balance changes nothing) and only taken once that mailbox is set up. Send an Idempotency-Key header so a retry never orders twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"description":"The domain by name: one registered elsewhere, or one you hold here","type":"string","minLength":3,"maxLength":253,"examples":["northwind-mail.com"]},"domainId":{"description":"A domain you hold here, by its id","type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"customerId":{"description":"Who this is for. Defaults to the customer a domain held here was bought for; required for any other domain","type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"moveNameservers":{"description":"Only for a domain held here whose DNS you pointed elsewhere (`domain_dns_elsewhere`): move it to mail nameservers anyway. Its records there are not copied","type":"boolean"},"buy":{"description":"Register the domain first: for one `checkMailboxDomains` would say is `available`","type":"boolean"},"mailboxes":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"username":{"type":"string","minLength":1,"maxLength":64,"examples":["jo"],"description":"The part before the @"},"firstName":{"type":"string","minLength":1,"maxLength":60,"examples":["Jo"]},"lastName":{"type":"string","minLength":1,"maxLength":60,"examples":["Bloggs"]},"profilePictureUrl":{"type":"string","maxLength":2048,"format":"uri"}},"required":["username","firstName","lastName"]}}},"required":["mailboxes"]}}}},"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":{"mailboxDomain":{"type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","createdAt"],"additionalProperties":false,"description":"The domain the mailboxes are on, connected by this call if it was not yet"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind-mail.com"]},"username":{"type":"string","examples":["jo"]},"firstName":{"type":"string","examples":["Jo"]},"lastName":{"type":"string","examples":["Bloggs"]},"profilePictureUrl":{"type":["string","null"]},"isAdmin":{"type":"boolean","description":"The domain's first mailbox, which administers its Google account. OAuth client IDs are granted through it"},"status":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"],"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},"setupStage":{"examples":["configuring_dns"],"description":"Where setup has got to while `provisioning`","type":["string","null"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the mailbox is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","email","username","firstName","lastName","profilePictureUrl","isAdmin","status","setupStage","failure","customerId","activatedAt","actor","createdAt"],"additionalProperties":false}},"registeredDomainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain bought for this order, when `buy` registered one"}},"required":["mailboxDomain","data","registeredDomainId"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `spend_limit_exceeded`, or `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `spend_limit_exceeded`, or `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}}}},"409":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_exists`, `domain_unavailable`, `domain_dns_elsewhere`, `domain_taken`, `mailbox_domain_deleting`, `mailbox_domain_busy`, `mailbox_exists`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_exists`, `domain_unavailable`, `domain_dns_elsewhere`, `domain_taken`, `mailbox_domain_deleting`, `mailbox_domain_busy`, `mailbox_exists`, 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"]},"examples":{"example1":{"value":{"error":"mailbox_domain_exists","message":"acme.com is already connected (mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA)","requestId":"req-4f"}},"example2":{"value":{"error":"domain_unavailable","message":"acme.com cannot be connected","requestId":"req-4f"}},"example3":{"value":{"error":"domain_dns_elsewhere","message":"acme.com uses its own nameservers (ns1.example.net), so its records cannot be copied over","requestId":"req-4f"}},"example4":{"value":{"error":"domain_taken","message":"This domain is already registered","requestId":"req-4f"}},"example5":{"value":{"error":"mailbox_domain_deleting","message":"This domain is being deleted","requestId":"req-4f"}},"example6":{"value":{"error":"mailbox_domain_busy","message":"Another change to this domain is in progress","requestId":"req-4f"}},"example7":{"value":{"error":"mailbox_exists","message":"jo@acme.com already exists","requestId":"req-4f"}},"example8":{"value":{"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 `domain_not_registered`, `registrant_required`, `not_available`, `invalid_domain`, `domain_not_active`, `domain_mismatch`, `customer_mismatch`, `customer_required`, `google_workspace_unavailable`, `ending_not_sold`, `premium_domain`, `mailbox_domain_failed`, `mailbox_limit`, `invalid_username`, `invalid_name`, `mailbox_purchase_refused`, `mailbox_provider_refused`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `domain_not_registered`, `registrant_required`, `not_available`, `invalid_domain`, `domain_not_active`, `domain_mismatch`, `customer_mismatch`, `customer_required`, `google_workspace_unavailable`, `ending_not_sold`, `premium_domain`, `mailbox_domain_failed`, `mailbox_limit`, `invalid_username`, `invalid_name`, `mailbox_purchase_refused`, `mailbox_provider_refused`, 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"]},"examples":{"example1":{"value":{"error":"domain_not_registered","message":"acme.com isn't registered. Send `buy: true` to register it with these mailboxes, or register it elsewhere first.","requestId":"req-4f"}},"example2":{"value":{"error":"registrant_required","message":"Set a registrant on this customer or a default one in your account settings, or send one with this order","requestId":"req-4f"}},"example3":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example4":{"value":{"error":"invalid_domain","message":"Enter a domain such as acme.com","requestId":"req-4f"}},"example5":{"value":{"error":"domain_not_active","message":"acme.com is not active, so it cannot be connected yet","requestId":"req-4f"}},"example6":{"value":{"error":"domain_mismatch","message":"domainId is acme.com, not acme.net","requestId":"req-4f"}},"example7":{"value":{"error":"customer_mismatch","message":"acme.com has mailboxes for another customer","requestId":"req-4f"}},"example8":{"value":{"error":"customer_required","message":"Name the customer these mailboxes are for","requestId":"req-4f"}},"example9":{"value":{"error":"google_workspace_unavailable","message":"acme.com is already used with Google Workspace elsewhere, so mailboxes cannot be set up on it","requestId":"req-4f"}},"example10":{"value":{"error":"ending_not_sold","message":"This ending is not sold here, so acme.com cannot be bought","requestId":"req-4f"}},"example11":{"value":{"error":"premium_domain","message":"Premium domain names cannot be bought here yet","requestId":"req-4f"}},"example12":{"value":{"error":"mailbox_domain_failed","message":"This domain never pointed at its nameservers. Regenerate them and try again","requestId":"req-4f"}},"example13":{"value":{"error":"mailbox_limit","message":"A domain takes 5 mailboxes and this one has 4","requestId":"req-4f"}},"example14":{"value":{"error":"invalid_username","message":"A username is the part before the @: letters, digits, dots, dashes and underscores","requestId":"req-4f"}},"example15":{"value":{"error":"invalid_name","message":"Every mailbox needs a first and a last name","requestId":"req-4f"}},"example16":{"value":{"error":"mailbox_purchase_refused","message":"The mailboxes could not be set up: domain is not active","requestId":"req-4f"}},"example17":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example18":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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 take this order; nothing was charged","requestId":"req-4f"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}},"get":{"operationId":"listMailboxes","summary":"List mailboxes","tags":["Mailboxes"],"description":"Your mailboxes, newest first. Sign-in details are only on the credentials route.","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":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"mailboxDomainId","required":false},{"schema":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"]},"in":"query","name":"status","required":false,"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"q","required":false,"description":"Text to look for anywhere in the address"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind-mail.com"]},"username":{"type":"string","examples":["jo"]},"firstName":{"type":"string","examples":["Jo"]},"lastName":{"type":"string","examples":["Bloggs"]},"profilePictureUrl":{"type":["string","null"]},"isAdmin":{"type":"boolean","description":"The domain's first mailbox, which administers its Google account. OAuth client IDs are granted through it"},"status":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"],"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},"setupStage":{"examples":["configuring_dns"],"description":"Where setup has got to while `provisioning`","type":["string","null"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the mailbox is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","email","username","firstName","lastName","profilePictureUrl","isAdmin","status","setupStage","failure","customerId","activatedAt","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mailbox-domains/check":{"post":{"operationId":"checkMailboxDomains","summary":"Check domains for mailboxes","tags":["Mailbox domains"],"description":"Before ordering on several domains at once: whether each is connected here already (and how many more mailboxes it takes), held here, free to buy (and at what price), registered elsewhere, or cannot have mailboxes, such as one already used with Google Workspace elsewhere. `registrant` says whether a domain bought with the order has someone to be registered to.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domains":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":253},"examples":[["northwind-mail.com","northwind-hq.com"]]},"customerId":{"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-mail.com"]},"state":{"type":"string","enum":["connected","held","available","elsewhere","unusable"],"description":"`connected`: already connected for mailboxes here, with `room` for more. `held`: a domain you hold here, whose nameservers we point for you. `available`: not registered, so an order can buy it (`price`). `elsewhere`: not bought here (see `registered`); you set two nameservers at its registrar after ordering. `unusable`: mailboxes cannot go on it, and `reason` says why"},"room":{"type":"integer","description":"How many more mailboxes it can take, of 10"},"mailboxDomainId":{"anyOf":[{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"For `connected`"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"For `held`"},"dnsElsewhere":{"type":"boolean","description":"For `held`: its DNS is served by nameservers of its own, so ordering moves them to the mail ones (send `moveNameservers`), and records kept there must be set again"},"registered":{"description":"For `elsewhere`: true when the registrar says it is registered, null when its ending is not sold here, so whether it is registered was not asked","type":["boolean","null"]},"price":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"For `available`: what registering it for a year costs you, WHOIS privacy included when your account adds it"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"For `available`, with `customerId`: what the customer pays for that year"},"reason":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"For `unusable`: why"}},"required":["domain","state","room","mailboxDomainId","domainId","dnsElsewhere","registered","price","customerPrice","reason"],"additionalProperties":false}},"registrant":{"anyOf":[{"type":"string","enum":["customer","default"]},{"type":"null"}],"description":"Who a domain bought for the customer is registered to: the customer's own registrant, or your default one. Null when there is neither, so none can be bought"}},"required":["data","registrant"],"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 `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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mailboxes/bulk":{"post":{"operationId":"createMailboxesBulk","summary":"Order mailboxes on several domains","tags":["Mailboxes"],"description":"Orders mailboxes on up to 50 domains in one call, buying the ones sent with `buy: true` first (for a year, to the customer's registrant or your default one). The wallet is checked for everything up front, so a short balance changes nothing. Each domain then succeeds or fails on its own: `results` says which, and a failed one can be sent again alone. A domain still being registered comes back `awaiting_domain`, its mailboxes paid for and set up once the registration finishes. Send an Idempotency-Key header so a retry never orders twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"],"description":"Who every domain and mailbox is for"},"domains":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","minLength":3,"maxLength":253,"examples":["northwind-mail.com"]},"buy":{"description":"Register it first: for a domain `checkMailboxDomains` says is `available`","type":"boolean"},"moveNameservers":{"description":"For a domain held here whose DNS is served elsewhere (`dnsElsewhere`)","type":"boolean"},"mailboxes":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"username":{"type":"string","minLength":1,"maxLength":64,"examples":["jo"],"description":"The part before the @"},"firstName":{"type":"string","minLength":1,"maxLength":60,"examples":["Jo"]},"lastName":{"type":"string","minLength":1,"maxLength":60,"examples":["Bloggs"]},"profilePictureUrl":{"type":"string","maxLength":2048,"format":"uri"}},"required":["username","firstName","lastName"]}}},"required":["domain","mailboxes"]}}},"required":["customerId","domains"]}}}},"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":{"results":{"type":"array","items":{"type":"object","properties":{"domain":{"type":"string","examples":["northwind-mail.com"]},"ok":{"type":"boolean"},"registeredDomainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain bought for this order, even when its mailboxes then failed"},"mailboxDomain":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","createdAt"],"additionalProperties":false},{"type":"null"}]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind-mail.com"]},"username":{"type":"string","examples":["jo"]},"firstName":{"type":"string","examples":["Jo"]},"lastName":{"type":"string","examples":["Bloggs"]},"profilePictureUrl":{"type":["string","null"]},"isAdmin":{"type":"boolean","description":"The domain's first mailbox, which administers its Google account. OAuth client IDs are granted through it"},"status":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"],"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},"setupStage":{"examples":["configuring_dns"],"description":"Where setup has got to while `provisioning`","type":["string","null"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the mailbox is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","email","username","firstName","lastName","profilePictureUrl","isAdmin","status","setupStage","failure","customerId","activatedAt","actor","createdAt"],"additionalProperties":false}},"error":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why this domain failed, when `ok` is false"}},"required":["domain","ok","registeredDomainId","mailboxDomain","data","error"],"additionalProperties":false}}},"required":["results"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `spend_limit_exceeded`, or `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `spend_limit_exceeded`, or `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `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 `registrant_required`, `not_available`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `registrant_required`, `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"]},"examples":{"example1":{"value":{"error":"registrant_required","message":"Set a registrant on this customer or a default one in your account settings, or send one with this order","requestId":"req-4f"}},"example2":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example3":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mailbox-domains":{"post":{"operationId":"connectMailboxDomain","summary":"Connect a domain","tags":["Mailbox domains"],"description":"Connects a domain without ordering anything, for when you want its nameservers before you buy: most often a domain registered elsewhere, so they can be set at its registrar ahead of time. Not needed otherwise: ordering mailboxes connects the domain by itself. Free.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"description":"The domain by name: one registered elsewhere, or one you hold here","type":"string","minLength":3,"maxLength":253,"examples":["northwind-mail.com"]},"domainId":{"description":"A domain you hold here, by its id","type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"customerId":{"description":"Who this is for. Defaults to the customer a domain held here was bought for; required for any other domain","type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"moveNameservers":{"description":"Only for a domain held here whose DNS you pointed elsewhere (`domain_dns_elsewhere`): move it to mail nameservers anyway. Its records there are not copied","type":"boolean"}}}}}},"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":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended` or `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended` or `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}}}},"409":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_exists`, `domain_unavailable`, `domain_dns_elsewhere`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_exists`, `domain_unavailable`, `domain_dns_elsewhere`, 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"]},"examples":{"example1":{"value":{"error":"mailbox_domain_exists","message":"acme.com is already connected (mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA)","requestId":"req-4f"}},"example2":{"value":{"error":"domain_unavailable","message":"acme.com cannot be connected","requestId":"req-4f"}},"example3":{"value":{"error":"domain_dns_elsewhere","message":"acme.com uses its own nameservers (ns1.example.net), so its records cannot be copied over","requestId":"req-4f"}},"example4":{"value":{"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 `not_available`, `invalid_domain`, `domain_not_active`, `domain_mismatch`, `customer_mismatch`, `customer_required`, `google_workspace_unavailable`, `mailbox_provider_refused`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `invalid_domain`, `domain_not_active`, `domain_mismatch`, `customer_mismatch`, `customer_required`, `google_workspace_unavailable`, `mailbox_provider_refused`, 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"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_domain","message":"Enter a domain such as acme.com","requestId":"req-4f"}},"example3":{"value":{"error":"domain_not_active","message":"acme.com is not active, so it cannot be connected yet","requestId":"req-4f"}},"example4":{"value":{"error":"domain_mismatch","message":"domainId is acme.com, not acme.net","requestId":"req-4f"}},"example5":{"value":{"error":"customer_mismatch","message":"acme.com has mailboxes for another customer","requestId":"req-4f"}},"example6":{"value":{"error":"customer_required","message":"Name the customer these mailboxes are for","requestId":"req-4f"}},"example7":{"value":{"error":"google_workspace_unavailable","message":"acme.com is already used with Google Workspace elsewhere, so mailboxes cannot be set up on it","requestId":"req-4f"}},"example8":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example9":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}},"get":{"operationId":"listMailboxDomains","summary":"List mailbox domains","tags":["Mailbox domains"],"description":"Your connected domains, 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":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"]},"in":"query","name":"status","required":false,"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false},{"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":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mailbox-domains/{id}":{"get":{"operationId":"getMailboxDomain","summary":"Get a mailbox domain","tags":["Mailbox domains"],"parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"updateMailboxDomain","summary":"Update a mailbox domain","tags":["Mailbox domains"],"description":"Fixes what the customer pays per mailbox on this domain.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"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":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"deleteMailboxDomain","summary":"Delete a mailbox domain","tags":["Mailbox domains"],"description":"Deletes the domain and every mailbox on it, for good: they stop renewing and are removed from Google. A mailbox cannot be deleted on its own. Nothing already paid is refunded; money held for mailboxes not yet set up goes back to your wallet. A domain held here keeps its nameservers: change them on the domain afterwards.","parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mailbox-domains/{id}/nameservers/regenerate":{"post":{"operationId":"regenerateMailboxDomainNameservers","summary":"Regenerate nameservers","tags":["Mailbox domains"],"description":"A fresh set of nameservers for a domain that is `failed` or still waiting. Set the new ones at the registrar (a domain held here is changed for you).","parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_connected`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_connected`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_connected","message":"This domain is already connected","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused` or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused` or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/mailboxes":{"post":{"operationId":"orderMailboxes","summary":"Add mailboxes to a domain","tags":["Mailbox domains"],"description":"Orders mailboxes on a connected domain by its id: the same as `POST /v1/mailboxes` naming the domain. The first ones or more later, up to 10 in all. Each month is held from your wallet now and only taken once that mailbox is set up, so one that fails costs nothing. The first mailbox on a domain administers its Google account. Follow `mailbox.active` or poll each mailbox; then read its sign-in details from the credentials route. Send an Idempotency-Key header so a retry never orders twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"mailboxes":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"username":{"type":"string","minLength":1,"maxLength":64,"examples":["jo"],"description":"The part before the @"},"firstName":{"type":"string","minLength":1,"maxLength":60,"examples":["Jo"]},"lastName":{"type":"string","minLength":1,"maxLength":60,"examples":["Bloggs"]},"profilePictureUrl":{"type":"string","maxLength":2048,"format":"uri"}},"required":["username","firstName","lastName"]}}},"required":["mailboxes"]}}}},"parameters":[{"schema":{"type":"string"},"example":"mdm_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":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind-mail.com"]},"username":{"type":"string","examples":["jo"]},"firstName":{"type":"string","examples":["Jo"]},"lastName":{"type":"string","examples":["Bloggs"]},"profilePictureUrl":{"type":["string","null"]},"isAdmin":{"type":"boolean","description":"The domain's first mailbox, which administers its Google account. OAuth client IDs are granted through it"},"status":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"],"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},"setupStage":{"examples":["configuring_dns"],"description":"Where setup has got to while `provisioning`","type":["string","null"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the mailbox is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","email","username","firstName","lastName","profilePictureUrl","isAdmin","status","setupStage","failure","customerId","activatedAt","actor","createdAt"],"additionalProperties":false}}},"required":["data"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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`, `spend_limit_exceeded`, or `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended`, `spend_limit_exceeded`, or `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"spend_limit_exceeded","message":"This credential may spend at most $500.00 on one order, and this one costs $750.00.","requestId":"req-4f"}},"example3":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_deleting`, `mailbox_domain_busy`, `mailbox_exists`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_deleting`, `mailbox_domain_busy`, `mailbox_exists`, 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"]},"examples":{"example1":{"value":{"error":"mailbox_domain_deleting","message":"This domain is being deleted","requestId":"req-4f"}},"example2":{"value":{"error":"mailbox_domain_busy","message":"Another change to this domain is in progress","requestId":"req-4f"}},"example3":{"value":{"error":"mailbox_exists","message":"jo@acme.com already exists","requestId":"req-4f"}},"example4":{"value":{"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 `not_available`, `mailbox_domain_failed`, `mailbox_limit`, `invalid_username`, `invalid_name`, `mailbox_purchase_refused`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `not_available`, `mailbox_domain_failed`, `mailbox_limit`, `invalid_username`, `invalid_name`, `mailbox_purchase_refused`, 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"]},"examples":{"example1":{"value":{"error":"not_available","message":"Domains are not open for live orders yet","requestId":"req-4f"}},"example2":{"value":{"error":"mailbox_domain_failed","message":"This domain never pointed at its nameservers. Regenerate them and try again","requestId":"req-4f"}},"example3":{"value":{"error":"mailbox_limit","message":"A domain takes 5 mailboxes and this one has 4","requestId":"req-4f"}},"example4":{"value":{"error":"invalid_username","message":"A username is the part before the @: letters, digits, dots, dashes and underscores","requestId":"req-4f"}},"example5":{"value":{"error":"invalid_name","message":"Every mailbox needs a first and a last name","requestId":"req-4f"}},"example6":{"value":{"error":"mailbox_purchase_refused","message":"The mailboxes could not be set up: domain is not active","requestId":"req-4f"}},"example7":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mailboxes/{id}":{"get":{"operationId":"getMailbox","summary":"Get a mailbox","tags":["Mailboxes"],"parameters":[{"schema":{"type":"string"},"example":"mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind-mail.com"]},"username":{"type":"string","examples":["jo"]},"firstName":{"type":"string","examples":["Jo"]},"lastName":{"type":"string","examples":["Bloggs"]},"profilePictureUrl":{"type":["string","null"]},"isAdmin":{"type":"boolean","description":"The domain's first mailbox, which administers its Google account. OAuth client IDs are granted through it"},"status":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"],"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},"setupStage":{"examples":["configuring_dns"],"description":"Where setup has got to while `provisioning`","type":["string","null"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the mailbox is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","email","username","firstName","lastName","profilePictureUrl","isAdmin","status","setupStage","failure","customerId","activatedAt","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"updateMailbox","summary":"Update a mailbox","tags":["Mailboxes"],"description":"Changes the name, username (and so the address), profile picture or password of a set-up mailbox.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":60},"lastName":{"type":"string","minLength":1,"maxLength":60},"username":{"type":"string","minLength":1,"maxLength":64},"profilePictureUrl":{"type":"string","maxLength":2048,"format":"uri"},"password":{"type":"string","minLength":12,"maxLength":100}}}}}},"parameters":[{"schema":{"type":"string"},"example":"mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind-mail.com"]},"username":{"type":"string","examples":["jo"]},"firstName":{"type":"string","examples":["Jo"]},"lastName":{"type":"string","examples":["Bloggs"]},"profilePictureUrl":{"type":["string","null"]},"isAdmin":{"type":"boolean","description":"The domain's first mailbox, which administers its Google account. OAuth client IDs are granted through it"},"status":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"],"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},"setupStage":{"examples":["configuring_dns"],"description":"Where setup has got to while `provisioning`","type":["string","null"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the mailbox is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","email","username","firstName","lastName","profilePictureUrl","isAdmin","status","setupStage","failure","customerId","activatedAt","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_not_active` or `mailbox_exists`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_not_active` or `mailbox_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"]},"examples":{"example1":{"value":{"error":"mailbox_not_active","message":"This mailbox is still being set up","requestId":"req-4f"}},"example2":{"value":{"error":"mailbox_exists","message":"jo@acme.com already exists","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_username`, `invalid_name`, `invalid_password`, `mailbox_provider_refused`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_username`, `invalid_name`, `invalid_password`, `mailbox_provider_refused`, or `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"]},"examples":{"example1":{"value":{"error":"invalid_username","message":"A username is the part before the @: letters, digits, dots, dashes and underscores","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_name","message":"Every mailbox needs a first and a last name","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_password","message":"A password is 12 to 100 characters long","requestId":"req-4f"}},"example4":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example5":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailboxes/{id}/picture":{"post":{"operationId":"uploadMailboxPicture","summary":"Upload a mailbox profile photo","tags":["Mailboxes"],"description":"Sets the Google profile photo of a set-up mailbox from an uploaded PNG, JPEG, WebP or GIF (at most 1 MB): the photo people see beside its mail. To use an image already online, send its address as `profilePictureUrl` to `PATCH /mailboxes/:id`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"dataUrl":{"type":"string","description":"A `data:` URL, such as `FileReader.readAsDataURL()` produces in a browser. The declared mime type in it is ignored - the real type is read from the file’s own bytes"}},"required":["dataUrl"]}}}},"parameters":[{"schema":{"type":"string"},"example":"mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["jo@northwind-mail.com"]},"username":{"type":"string","examples":["jo"]},"firstName":{"type":"string","examples":["Jo"]},"lastName":{"type":"string","examples":["Bloggs"]},"profilePictureUrl":{"type":["string","null"]},"isAdmin":{"type":"boolean","description":"The domain's first mailbox, which administers its Google account. OAuth client IDs are granted through it"},"status":{"type":"string","enum":["queued","provisioning","active","failed","cancelled"],"description":"`queued` until the domain is connected; `provisioning` while it is being set up (minutes to a few hours); `active` with its sign-in details ready; `failed` if it could not be set up, when nothing is charged for it; `cancelled` once its domain is deleted"},"setupStage":{"examples":["configuring_dns"],"description":"Where setup has got to while `provisioning`","type":["string","null"]},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the mailbox is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"activatedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","email","username","firstName","lastName","profilePictureUrl","isAdmin","status","setupStage","failure","customerId","activatedAt","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_not_active","message":"This mailbox is still being set up","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `picture_too_large`, `picture_unsupported_type`, `mailbox_provider_refused`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `picture_too_large`, `picture_unsupported_type`, `mailbox_provider_refused`, or `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"]},"examples":{"example1":{"value":{"error":"picture_too_large","message":"That image is larger than 1 MB","requestId":"req-4f"}},"example2":{"value":{"error":"picture_unsupported_type","message":"Upload a PNG, JPEG, WebP or GIF","requestId":"req-4f"}},"example3":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example4":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailboxes/{id}/credentials":{"post":{"operationId":"revealMailboxCredentials","summary":"Reveal sign-in details","tags":["Mailboxes"],"description":"The mailbox's password, app password and two-step verification secret, with the Gmail IMAP and SMTP settings. Each reveal is recorded in your activity log. Two ways to connect: sign in through OAuth with a client ID granted on the domain, or use the app password over IMAP/SMTP.","parameters":[{"schema":{"type":"string"},"example":"mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"email":{"type":"string","examples":["jo@northwind-mail.com"]},"password":{"type":"string"},"appPassword":{"type":"string","description":"For IMAP and SMTP, in place of the password"},"totpSecret":{"type":"string","description":"The base32 seed of its two-step verification"},"imap":{"type":"object","properties":{"host":{"type":"string","enum":["imap.gmail.com"]},"port":{"type":"number","enum":[993]},"security":{"type":"string","enum":["ssl"]}},"required":["host","port","security"],"additionalProperties":false},"smtp":{"type":"object","properties":{"host":{"type":"string","enum":["smtp.gmail.com"]},"port":{"type":"number","enum":[587]},"security":{"type":"string","enum":["starttls"]}},"required":["host","port","security"],"additionalProperties":false}},"required":["email","password","appPassword","totpSecret","imap","smtp"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_not_active","message":"This mailbox is still being set up","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mailboxes/{id}/totp":{"post":{"operationId":"getMailboxTotp","summary":"Get a sign-in code","tags":["Mailboxes"],"description":"The mailbox's current two-step verification code.","parameters":[{"schema":{"type":"string"},"example":"mbx_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"code":{"type":"string","examples":["492817"]},"expiresAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["code","expiresAt"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_not_active","message":"This mailbox is still being set up","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/dns/records":{"get":{"operationId":"listMailboxDomainDnsRecords","summary":"List DNS records","tags":["Mailbox DNS"],"description":"The domain's DNS, hosted alongside its mailboxes. Records mail depends on are marked `protected` and cannot be changed here.","parameters":[{"schema":{"type":"string"},"example":"mdm_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":["6512bd43d9caa6e02c990b0a"]},"host":{"type":"string","examples":["www"]},"type":{"type":"string","examples":["CNAME"],"description":"The record type, as the registrar reports it — not only a type mail needs"},"value":{"type":"string","examples":["northwind.netlify.app"]},"ttl":{"type":"integer"},"priority":{"type":"integer"},"protected":{"type":"boolean","description":"Mail depends on this record (MX, SPF, DKIM, DMARC, nameservers): it cannot be changed here"}},"required":["id","host","type","value","ttl","protected"],"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"}}}},"409":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_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":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}},"post":{"operationId":"addMailboxDomainDnsRecords","summary":"Add DNS records","tags":["Mailbox DNS"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"records":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"host":{"type":"string","minLength":1,"maxLength":253,"examples":["www"],"description":"`@` for the domain itself"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA"]},"value":{"type":"string","minLength":1,"maxLength":2048},"ttl":{"type":"integer","minimum":60,"maximum":86400},"priority":{"type":"integer","minimum":0,"maximum":65535}},"required":["host","type","value"]}}},"required":["records"]}}}},"parameters":[{"schema":{"type":"string"},"example":"mdm_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":["6512bd43d9caa6e02c990b0a"]},"host":{"type":"string","examples":["www"]},"type":{"type":"string","examples":["CNAME"],"description":"The record type, as the registrar reports it — not only a type mail needs"},"value":{"type":"string","examples":["northwind.netlify.app"]},"ttl":{"type":"integer"},"priority":{"type":"integer"},"protected":{"type":"boolean","description":"Mail depends on this record (MX, SPF, DKIM, DMARC, nameservers): it cannot be changed here"}},"required":["id","host","type","value","ttl","protected"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"error":"record_protected","message":"Mail depends on this record (MX, SPF, DKIM, DMARC or the nameservers), so it cannot be changed here","requestId":"req-4f"}},"example3":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/dns/records/{recordId}":{"patch":{"operationId":"updateMailboxDomainDnsRecord","summary":"Update a DNS record","tags":["Mailbox DNS"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"host":{"type":"string","minLength":1,"maxLength":253,"examples":["www"],"description":"`@` for the domain itself"},"type":{"type":"string","enum":["A","AAAA","CNAME","MX","TXT","SRV","CAA"]},"value":{"type":"string","minLength":1,"maxLength":2048},"ttl":{"type":"integer","minimum":60,"maximum":86400},"priority":{"type":"integer","minimum":0,"maximum":65535}},"required":["host","type","value"]}}}},"parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"path","name":"recordId","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":["6512bd43d9caa6e02c990b0a"]},"host":{"type":"string","examples":["www"]},"type":{"type":"string","examples":["CNAME"],"description":"The record type, as the registrar reports it — not only a type mail needs"},"value":{"type":"string","examples":["northwind.netlify.app"]},"ttl":{"type":"integer"},"priority":{"type":"integer"},"protected":{"type":"boolean","description":"Mail depends on this record (MX, SPF, DKIM, DMARC, nameservers): it cannot be changed here"}},"required":["id","host","type","value","ttl","protected"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"error":"record_protected","message":"Mail depends on this record (MX, SPF, DKIM, DMARC or the nameservers), so it cannot be changed here","requestId":"req-4f"}},"example3":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}},"delete":{"operationId":"deleteMailboxDomainDnsRecord","summary":"Delete a DNS record","tags":["Mailbox DNS"],"parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"path","name":"recordId","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":["6512bd43d9caa6e02c990b0a"]},"host":{"type":"string","examples":["www"]},"type":{"type":"string","examples":["CNAME"],"description":"The record type, as the registrar reports it — not only a type mail needs"},"value":{"type":"string","examples":["northwind.netlify.app"]},"ttl":{"type":"integer"},"priority":{"type":"integer"},"protected":{"type":"boolean","description":"Mail depends on this record (MX, SPF, DKIM, DMARC, nameservers): it cannot be changed here"}},"required":["id","host","type","value","ttl","protected"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"error":"record_protected","message":"Mail depends on this record (MX, SPF, DKIM, DMARC or the nameservers), so it cannot be changed here","requestId":"req-4f"}},"example3":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/dns/check":{"post":{"operationId":"checkMailboxDomainDns","summary":"Check mail DNS","tags":["Mailbox DNS"],"description":"Whether every record the mailboxes need is in place.","parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"health":{"type":"string","enum":["healthy","critical","issues_found","unknown"]},"needsRepair":{"type":"boolean"},"records":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"type":{"type":"string","enum":["MX","TXT"]},"host":{"type":"string"},"status":{"type":"string","enum":["valid","ok","missing"]},"currentValue":{"type":"string"},"expectedValue":{"type":"string"},"issue":{"type":"string"}},"required":["label","type","host","status"],"additionalProperties":false}}},"required":["health","needsRepair","records"],"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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_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":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/dns/repair":{"post":{"operationId":"repairMailboxDomainDns","summary":"Repair mail DNS","tags":["Mailbox DNS"],"description":"Puts back any mail record that is missing or wrong, then checks again.","parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"health":{"type":"string","enum":["healthy","critical","issues_found","unknown"]},"needsRepair":{"type":"boolean"},"records":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"type":{"type":"string","enum":["MX","TXT"]},"host":{"type":"string"},"status":{"type":"string","enum":["valid","ok","missing"]},"currentValue":{"type":"string"},"expectedValue":{"type":"string"},"issue":{"type":"string"}},"required":["label","type","host","status"],"additionalProperties":false}}},"required":["health","needsRepair","records"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `record_protected`, or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"error":"record_protected","message":"Mail depends on this record (MX, SPF, DKIM, DMARC or the nameservers), so it cannot be changed here","requestId":"req-4f"}},"example3":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/forwarding":{"put":{"operationId":"setMailboxDomainForwarding","summary":"Set website forwarding","tags":["Mailbox domain settings"],"description":"Redirects the domain's website to a URL. `url: null` removes the redirect.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"anyOf":[{"type":"string","maxLength":2048},{"type":"null"}],"examples":["https://northwind.com"]},"captcha":{"description":"Show a captcha before redirecting","type":"boolean"}},"required":["url"]}}}},"parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `invalid_url`, `invalid_forwarding`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `invalid_url`, `invalid_forwarding`, or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_url","message":"Enter a URL starting with http:// or https://","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_forwarding","message":"A captcha needs a URL to forward to","requestId":"req-4f"}},"example4":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/dmarc":{"put":{"operationId":"setMailboxDomainDmarc","summary":"Set DMARC","tags":["Mailbox domain settings"],"description":"Sets the domain's DMARC policy. `DELETE` removes it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reportingEmail":{"type":"string","format":"email","examples":["dmarc@northwind.com"]},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer","minimum":1,"maximum":100},"forensicEmail":{"type":"string","format":"email"},"spfAlignment":{"type":"string","enum":["r","s"]},"dkimAlignment":{"type":"string","enum":["r","s"]}},"required":["reportingEmail","policy"]}}}},"parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused` or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused` or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}},"delete":{"operationId":"removeMailboxDomainDmarc","summary":"Remove DMARC","tags":["Mailbox domain settings"],"parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"domain":{"type":"string","examples":["northwind-mail.com"]},"status":{"type":"string","enum":["awaiting_domain","awaiting_nameservers","propagating","active","failed","deleting","deleted"],"description":"`awaiting_domain` while a domain bought with the order is still being registered; `awaiting_nameservers` until the domain points at `nameservers`; `propagating` once we have pointed a domain held here ourselves; `active` when mailboxes can be set up on it; `failed` when it never pointed there in time (regenerate the nameservers and try again); `deleting` then `deleted` once you delete it"},"source":{"type":"string","enum":["resellerhq","external"],"description":"`resellerhq` for a domain you hold here, whose nameservers we change for you; `external` for one registered elsewhere, whose nameservers you change at its registrar"},"domainId":{"anyOf":[{"type":"string","examples":["dom_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The domain held here, for `resellerhq`"},"nameserversManaged":{"type":"boolean","description":"True when we point the domain at `nameservers` ourselves (a domain held here): there is nothing for you to do. False when you set them at its registrar"},"nameservers":{"type":"array","items":{"type":"string","examples":["ns1.example-dns.net"]},"description":"Where the domain must point. Its DNS is hosted there from then on"},"failure":{"anyOf":[{"type":"object","properties":{"code":{"type":"string","examples":["DOMAIN_IN_USE_GOOGLE"]},"message":{"type":"string","examples":["Domain is already in use in Google Workspace."]}},"required":["code","message"],"additionalProperties":false},{"type":"null"}],"description":"Why the domain is `failed`"},"customerId":{"anyOf":[{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"unitPrice":{"type":"integer","minimum":0,"examples":[450],"description":"What you pay per mailbox per month on this domain, fixed when it was connected"},"customerPrice":{"anyOf":[{"type":"integer","minimum":0,"examples":[450],"description":"Minor units (US cents)"},{"type":"null"}],"description":"What the customer pays per mailbox, when fixed here"},"periodEndsAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the month paid for ends. Every set-up mailbox on the domain renews together then. Null until the first mailbox is ordered"},"unpaidSince":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When the renewal now due first could not be charged. Null when nothing is owed"},"deletesAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"description":"When an unpaid domain is deleted with its mailboxes. Add funds before then"},"forwarding":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","examples":["https://northwind.com"]},"captcha":{"type":"boolean"}},"required":["url","captcha"],"additionalProperties":false},{"type":"null"}],"description":"Where the domain's website redirects"},"dmarc":{"anyOf":[{"type":"object","properties":{"reportingEmail":{"type":"string"},"policy":{"type":"string","enum":["none","quarantine","reject"]},"subdomainPolicy":{"type":"string","enum":["none","quarantine","reject"]},"percentage":{"type":"integer"}},"required":["reportingEmail","policy"],"additionalProperties":false},{"type":"null"}]},"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"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","domain","status","source","domainId","nameserversManaged","nameservers","failure","customerId","unitPrice","customerPrice","periodEndsAt","unpaidSince","deletesAt","forwarding","dmarc","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused` or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused` or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}}},"/v1/mailbox-domains/{id}/client-ids":{"post":{"operationId":"grantMailboxDomainClientId","summary":"Grant an OAuth client ID","tags":["Mailbox domain settings"],"description":"Trusts your app's Google OAuth client on the domain's Google account, so its mailboxes can sign in to it. `delegated: true` grants domain-wide delegation for `scopes` instead, so the app can act as any mailbox on the domain without each one signing in. Needs the domain’s admin mailbox set up. We follow the request and send `client_id.completed` or `client_id.failed`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","minLength":6,"maxLength":200,"examples":["102938475610293847561"]},"delegated":{"type":"boolean"},"scopes":{"description":"Full scope URLs, for a delegated client only","maxItems":50,"type":"array","items":{"type":"string","examples":["https://mail.google.com/"]}}},"required":["clientId"]}}}},"parameters":[{"schema":{"type":"string"},"example":"mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["cid_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"clientId":{"type":"string","examples":["102938475610293847561"]},"delegated":{"type":"boolean","description":"True for domain-wide delegation, false for a trusted app"},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending","completed","failed"]},"error":{"type":["string","null"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","clientId","delegated","scopes","status","error","completedAt","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `mailbox_domain_not_active`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `mailbox_domain_not_active`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"mailbox_domain_not_active","message":"This domain is not connected yet","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `invalid_client_id`, `invalid_scopes`, `no_admin_mailbox`, or `not_available`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `mailbox_provider_refused`, `invalid_client_id`, `invalid_scopes`, `no_admin_mailbox`, or `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"]},"examples":{"example1":{"value":{"error":"mailbox_provider_refused","message":"The mailbox provider refused this change","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_client_id","message":"A Google client ID is a number, or ends in .apps.googleusercontent.com","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_scopes","message":"Scopes are only for a client with domain-wide delegation","requestId":"req-4f"}},"example4":{"value":{"error":"no_admin_mailbox","message":"The first mailbox on this domain administers its Google account and must be set up first","requestId":"req-4f"}},"example5":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"503":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_unavailable`.","content":{"application/json":{"schema":{"description":"The upstream provider is unavailable. Nothing was charged. `error` is `mailboxes_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":"mailboxes_unavailable","message":"Mailboxes cannot be reached right now. Nothing was changed; try again shortly","requestId":"req-4f"}}}}}},"get":{"operationId":"listMailboxDomainClientIds","summary":"List OAuth client IDs","tags":["Mailbox domain settings"],"parameters":[{"schema":{"type":"string"},"example":"mdm_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":["cid_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"mailboxDomainId":{"type":"string","examples":["mdm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"clientId":{"type":"string","examples":["102938475610293847561"]},"delegated":{"type":"boolean","description":"True for domain-wide delegation, false for a trusted app"},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending","completed","failed"]},"error":{"type":["string","null"]},"completedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","mailboxDomainId","clientId","delegated","scopes","status","error","completedAt","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"}}}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"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","cancellableFrom","createdAt"],"additionalProperties":false}},"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 placed this order"},"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","actor","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"},"autoRenew":{"type":"boolean","description":"Whether this domain renews itself from your wallet shortly before it expires"},"dns":{"type":"object","properties":{"supported":{"type":"boolean","description":"Whether the registrar behind this domain hosts DNS zones at all"},"hosted":{"type":"boolean","description":"Whether we host this domain's DNS. Turn it on with `PUT /v1/domains/{id}/dns`"},"dnssecSupported":{"type":"boolean","description":"Whether this ending can be signed with DNSSEC at all - a fact about the ending, not about the registrar: it can differ from `supported`"},"signed":{"type":"boolean","description":"Whether this domain is signed with DNSSEC right now"},"dsRecords":{"type":"array","items":{"type":"object","properties":{"keyTag":{"type":"integer"},"algorithm":{"type":"integer"},"digestType":{"type":"integer"},"digest":{"type":"string","examples":["49FCE7"],"description":"Hex"}},"required":["keyTag","algorithm","digestType","digest"],"additionalProperties":false,"description":"One DS record the registry holds for a domain right now"},"description":"The DS records the registry holds for this domain right now. Empty when not signed"},"keys":{"type":"array","items":{"type":"object","properties":{"flags":{"anyOf":[{"type":"number","enum":[256]},{"type":"number","enum":[257]}],"description":"256 is a zone-signing key (ZSK), 257 a key-signing key (KSK)"},"algorithm":{"type":"integer","minimum":0,"maximum":255},"publicKey":{"type":"string","minLength":1,"maxLength":4096,"description":"Base64, from your DNS provider. Whitespace is stripped before it is sent on"}},"required":["flags","algorithm","publicKey"],"additionalProperties":false,"description":"One DNSSEC key for a domain whose DNS is hosted elsewhere"},"description":"The DNSSEC keys last sent for this domain. Only meaningful when `dnssecSupported` is true and `hosted` is false; set them with `PUT /v1/domains/{id}/dnssec`"}},"required":["supported","hosted","dnssecSupported","signed","dsRecords","keys"],"additionalProperties":false,"description":"Hosted DNS and DNSSEC for this domain. Every field is always there"},"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 placed this order"}},"required":["id","domain","status","customerId","unitPrice","customerPrice","paidTotal","registeredAt","expiresAt","nameservers","customNameservers","contact","contacts","locked","suspended","privacy","privacyPrice","autoRenew","dns","actor"],"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":["provisioning","active","cancelled"],"description":"`provisioning` while the mailboxes are being created with the vendor, which takes a moment and has no webhook to announce it; we poll until every one is ready. It is charged, billed and renewed from the moment it is bought either way"},"provisioningStalled":{"type":"boolean","examples":[false],"description":"True when the mailboxes did not come up and we have stopped waiting. The licence stays `provisioning`, our staff have been told, and the seats are still billed"},"cancelAtPeriodEnd":{"type":"boolean","examples":[false],"description":"True when this licence is set to end at `periodEndsAt` instead of renewing"},"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"},"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 placed this order"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","plan","planName","vendor","domain","seats","status","provisioningStalled","cancelAtPeriodEnd","customerId","unitPrice","customerPrice","paidTotal","periodEndsAt","unpaidSince","cancelsAt","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/pricing/catalogue-drops":{"get":{"operationId":"listCatalogueDrops","summary":"List wholesale price drops","tags":["Pricing"],"description":"Domain endings whose upstream wholesale cost is currently lower than usual, for a window the registrar itself named (issue #1023's suggestion): one row per ending, gone once the window ends or the price goes back up. Shared across every account on this installation, since the wholesale price is the registrar's, not any one reseller's. Never changes what a customer is charged; create a promotion of your own to pass a drop on.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"ending":{"type":"string","examples":["com"]},"oldCost":{"type":"integer","minimum":0,"examples":[1440],"description":"The wholesale cost before this drop"},"newCost":{"type":"integer","minimum":0,"examples":[1440],"description":"The wholesale cost now, lower than `oldCost`"},"endsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"When the registrar's own promo window ends"}},"required":["ending","oldCost","newCost","endsAt"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Price lists"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","mailbox"]},"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","transfer"]},"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"},"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 created or last updated 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","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Price lists"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","mailbox"]},"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","transfer"]},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","mailbox"]},"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","transfer"]},"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"},"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 created or last updated 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","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, or `invalid_rate`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, or `invalid_rate`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}},"example2":{"value":{"error":"duplicate_rule","message":"Two rules cover exactly the same items","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_rate","message":"A list in US dollars has a rate of 1000000","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Price lists"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","mailbox"]},"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","transfer"]},"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"},"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 created or last updated 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","actor","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Price lists"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","mailbox"]},"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","transfer"]},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","mailbox"]},"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","transfer"]},"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"},"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 created or last updated 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","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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_rate`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, or `invalid_rate`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}},"example2":{"value":{"error":"duplicate_rule","message":"Two rules cover exactly the same items","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_rate","message":"A list in US dollars has a rate of 1000000","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Price lists"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Price lists"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","mailbox"]},"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","transfer"]},"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","mailbox"]},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"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"},"normalPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer would pay for one unit with no promotion, in `currency`. The same as `price` when none applied"},"discount":{"type":"integer","minimum":0,"examples":[1440],"description":"What a promotion took off `normalPrice`. Zero when none applied"},"promotion":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"code":{"examples":["LAUNCH25"],"description":"The coupon code this promotion needs. Null when everyone on the list gets it","type":["string","null"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-01T00:00:00.000Z"],"description":"When the promotional price stops applying"}},"required":["id","code","endsAt"],"additionalProperties":false},{"type":"null"}],"description":"The promotion that set the price. Null when none applied"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored","normalPrice","discount","promotion"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"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"},"normalPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer would pay for one unit with no promotion, in `currency`. The same as `price` when none applied"},"discount":{"type":"integer","minimum":0,"examples":[1440],"description":"What a promotion took off `normalPrice`. Zero when none applied"},"promotion":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"code":{"examples":["LAUNCH25"],"description":"The coupon code this promotion needs. Null when everyone on the list gets it","type":["string","null"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-01T00:00:00.000Z"],"description":"When the promotional price stops applying"}},"required":["id","code","endsAt"],"additionalProperties":false},{"type":"null"}],"description":"The promotion that set the price. Null when none applied"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored","normalPrice","discount","promotion"],"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`, or `invalid_rate`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `too_many_rules`, `duplicate_rule`, or `invalid_rate`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}},"example2":{"value":{"error":"duplicate_rule","message":"Two rules cover exactly the same items","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_rate","message":"A list in US dollars has a rate of 1000000","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Contract prices"],"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","mailbox"]},"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","transfer"]},"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"]},"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 last set this customer's contract prices"}},"required":["id","product","kind","value","actor"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Contract prices"],"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","mailbox"]},"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","transfer"]},"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","mailbox"]},"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","transfer"]},"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"]},"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 last set this customer's contract prices"}},"required":["id","product","kind","value","actor"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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"]},"examples":{"example1":{"value":{"error":"too_many_rules","message":"A price list holds at most 200 rules","requestId":"req-4f"}},"example2":{"value":{"error":"duplicate_rule","message":"Two rules cover exactly the same items","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_dates","message":"A contract price must end after it starts","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Price lists"],"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. A promotion everyone on the list gets is counted without asking; send `coupon` to see what the promotion behind a code would do. A coupon that cannot be used is simply not applied.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"priceListId":{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"coupon":{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},"items":{"minItems":1,"maxItems":200,"type":"array","items":{"type":"object","properties":{"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"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","transfer"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"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"},"normalPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer would pay for one unit with no promotion, in `currency`. The same as `price` when none applied"},"discount":{"type":"integer","minimum":0,"examples":[1440],"description":"What a promotion took off `normalPrice`. Zero when none applied"},"promotion":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"code":{"examples":["LAUNCH25"],"description":"The coupon code this promotion needs. Null when everyone on the list gets it","type":["string","null"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-01T00:00:00.000Z"],"description":"When the promotional price stops applying"}},"required":["id","code","endsAt"],"additionalProperties":false},{"type":"null"}],"description":"The promotion that set the price. Null when none applied"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored","normalPrice","discount","promotion"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Sales"],"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","mailbox"]},"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","mailbox"]},"action":{"type":"string","enum":["new","renew","restore","transfer"],"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","enum":["hold","domain","domain_transfer","domain_privacy","licence","mailbox","mailbox_domain","number_order","number_rental","reconciliation_case","stripe_checkout_session","stripe_refund","stripe_dispute"]},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Sales"],"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, each group summing to the ungrouped total. Always in US cents, whatever currency each sale was charged in, and net of credit notes issued against those sales.","parameters":[{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"customerId","required":false},{"schema":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"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"},{"schema":{"type":"string","enum":["product","customer","priceList","level","month","day"]},"in":"query","name":"groupBy","required":false,"description":"Splits the totals. `month` is the calendar month in UTC, as `2026-10`, and `day` the calendar day in UTC, as `2026-10-21`"}],"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, net of credit notes"},"credited":{"type":"integer","minimum":0,"examples":[0],"description":"What credit notes have taken off `price`, each line converted at its own sale's rate. A flat-amount credit note names no sale and so is not reflected here"},"profit":{"type":"integer","examples":[2400],"description":"`price` less `cost`. Falls with `price` when a sale is credited, and can go below zero for that sale"},"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, month or day. 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, net of credit notes"},"credited":{"type":"integer","minimum":0,"examples":[0],"description":"What credit notes have taken off `price`, each line converted at its own sale's rate. A flat-amount credit note names no sale and so is not reflected here"},"profit":{"type":"integer","examples":[2400],"description":"`price` less `cost`. Falls with `price` when a sale is credited, and can go below zero for that sale"},"marginBps":{"type":"integer","examples":[1667],"description":"Profit as a share of `price`, in basis points"}},"required":["key","count","cost","price","credited","profit","marginBps"],"additionalProperties":false}}},"required":["count","cost","price","credited","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/promotions":{"get":{"operationId":"listPromotions","summary":"List promotions","tags":["Promotions"],"description":"Every offer you have run, newest first. An account holds at most 200 of them, so they all come back at once.","parameters":[{"schema":{"type":"string"},"example":"prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"priceListId","required":false,"description":"Only offers on this list"},{"schema":{"type":"string","enum":["scheduled","live","ended","used_up"]},"in":"query","name":"status","required":false,"description":"`scheduled` has not started, `live` is running now, `ended` is past its dates and `used_up` has been used as often as it allows"}],"responses":{"200":{"description":"The offers you have run","content":{"application/json":{"schema":{"description":"The offers you have run","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Launch offer on .com"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The list the offer belongs to. Null when it covers every list"},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"match":{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},{"type":"null"}],"description":"What it is narrowed to within its product, or the first of `matches` when it names several. Null for all of it"},"matches":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"}},{"type":"null"}],"examples":[["com","net","org"]],"description":"Everything it is narrowed to: one or several. Null for all of it"},"term":{"anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}],"description":"The rental length it is narrowed to. Null for every length"},"applies":{"type":"string","enum":["new","renew","both"],"description":"`new` is first purchases only, which is what an introductory offer means; `renew` is renewals only; `both` is every purchase, a restore included"},"kind":{"type":"string","enum":["fixed","percent","amount"],"description":"`fixed` is the promotional price itself; `percent` takes a share off the normal price; `amount` takes a fixed sum off it"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Minor units of the list's currency for `fixed` and `amount`; basis points for `percent` (2500 is 25% off)"},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"]},"code":{"anyOf":[{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},{"type":"null"}],"description":"The coupon code an order has to send. Null when everyone on the list gets the offer"},"maxUses":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[100],"description":"How many times it may be used in all. Null for no limit"},"maxPerCustomer":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[1],"description":"How many times one customer may use it. Null for no limit"},"allowBelowCost":{"type":"boolean","description":"Lets the promotional price sit under what you pay for the item"},"status":{"type":"string","enum":["scheduled","live","ended","used_up"],"description":"`scheduled` has not started, `live` is running now, `ended` is past its dates and `used_up` has been used as often as it allows"},"uses":{"type":"integer","examples":[12],"description":"How many times it has been used"},"discountUsd":{"type":"integer","minimum":0,"examples":[1440],"description":"What it has taken off in all, in US cents"},"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","priceListId","product","match","matches","term","applies","kind","value","startsAt","endsAt","code","maxUses","maxPerCustomer","allowBelowCost","status","uses","discountUsd","createdAt","updatedAt"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"createPromotion","summary":"Create a promotion","tags":["Promotions"],"description":"A price for the dates it runs, on one list or on every list. With no `code` everyone on the list gets it; with one, only an order that sends that coupon. It changes what the customer is charged and nothing else: your wallet is still charged wholesale. An offer that would have to sell under what you pay is refused unless you set `allowBelowCost`; `POST /v1/promotions/impact` shows the margin either way first.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Launch offer on .com"]},"priceListId":{"description":"The list the offer belongs to. Null, or left out, covers every list","anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"match":{"description":"Narrows the offer within its product. Null, or left out, covers the whole product; send null to take a narrowing off again. For several at once, send `matches`","anyOf":[{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},{"type":"null"}]},"matches":{"examples":[["com","net","org"]],"description":"Narrows the offer to any of these: several domain endings, countries or plans in one promotion. Send this or `match`, not both; null takes the narrowing off again","anyOf":[{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"}},{"type":"null"}]},"term":{"description":"Narrows a number offer to one rental length. Null, or left out, covers every length","anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}]},"kind":{"type":"string","enum":["fixed","percent","amount"],"description":"`fixed` is the promotional price itself; `percent` takes a share off the normal price; `amount` takes a fixed sum off it"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Minor units of the list's currency for `fixed` and `amount`; basis points for `percent` (2500 is 25% off)"},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"When the offer starts"},"endsAt":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"],"description":"When it stops. A purchase at or after this moment pays the normal price"},"code":{"description":"The coupon code an order has to send. Null, or left out, and everyone on the list gets the offer without asking. A code is never handed out twice, even after the offer ends","anyOf":[{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},{"type":"null"}]},"maxUses":{"examples":[100],"description":"How many times it may be used in all. Null, or left out, for no limit","anyOf":[{"type":"integer","minimum":1,"maximum":1000000},{"type":"null"}]},"maxPerCustomer":{"examples":[1],"description":"How many times one customer may use it. Null, or left out, for no limit","anyOf":[{"type":"integer","minimum":1,"maximum":1000000},{"type":"null"}]},"applies":{"default":"new","type":"string","enum":["new","renew","both"],"description":"`new` is first purchases only, which is what an introductory offer means; `renew` is renewals only; `both` is every purchase, a restore included"},"allowBelowCost":{"default":false,"type":"boolean","description":"Lets the promotional price sit under what you pay for the item"}},"required":["name","product","kind","value","startsAt","endsAt"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Launch offer on .com"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The list the offer belongs to. Null when it covers every list"},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"match":{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},{"type":"null"}],"description":"What it is narrowed to within its product, or the first of `matches` when it names several. Null for all of it"},"matches":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"}},{"type":"null"}],"examples":[["com","net","org"]],"description":"Everything it is narrowed to: one or several. Null for all of it"},"term":{"anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}],"description":"The rental length it is narrowed to. Null for every length"},"applies":{"type":"string","enum":["new","renew","both"],"description":"`new` is first purchases only, which is what an introductory offer means; `renew` is renewals only; `both` is every purchase, a restore included"},"kind":{"type":"string","enum":["fixed","percent","amount"],"description":"`fixed` is the promotional price itself; `percent` takes a share off the normal price; `amount` takes a fixed sum off it"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Minor units of the list's currency for `fixed` and `amount`; basis points for `percent` (2500 is 25% off)"},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"]},"code":{"anyOf":[{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},{"type":"null"}],"description":"The coupon code an order has to send. Null when everyone on the list gets the offer"},"maxUses":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[100],"description":"How many times it may be used in all. Null for no limit"},"maxPerCustomer":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[1],"description":"How many times one customer may use it. Null for no limit"},"allowBelowCost":{"type":"boolean","description":"Lets the promotional price sit under what you pay for the item"},"status":{"type":"string","enum":["scheduled","live","ended","used_up"],"description":"`scheduled` has not started, `live` is running now, `ended` is past its dates and `used_up` has been used as often as it allows"},"uses":{"type":"integer","examples":[12],"description":"How many times it has been used"},"discountUsd":{"type":"integer","minimum":0,"examples":[1440],"description":"What it has taken off in all, in US cents"},"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","priceListId","product","match","matches","term","applies","kind","value","startsAt","endsAt","code","maxUses","maxPerCustomer","allowBelowCost","status","uses","discountUsd","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `too_many_promotions` or `duplicate_coupon`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `too_many_promotions` or `duplicate_coupon`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"too_many_promotions","message":"An account holds at most 200 promotions","requestId":"req-4f"}},"example2":{"value":{"error":"duplicate_coupon","message":"That coupon code is already in use","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `promotion_below_cost` or `invalid_dates`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `promotion_below_cost` 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"]},"examples":{"example1":{"value":{"error":"promotion_below_cost","message":"This promotion would sell under what you pay; allow selling below cost to run it anyway","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_dates","message":"A contract price must end after it starts","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/promotions/impact":{"post":{"operationId":"previewPromotion","summary":"Preview a promotion","tags":["Promotions"],"description":"Takes the offer you are thinking of running and saves nothing. Says how many customers are on its list, how many things they hold, and for a sample of those what one unit costs them now and what it would cost on the offer. `belowCost` counts the ones that would sell under what you pay: this route reports them rather than refusing the offer, since seeing the margin is the point of it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Launch offer on .com"]},"priceListId":{"description":"The list the offer belongs to. Null, or left out, covers every list","anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"match":{"description":"Narrows the offer within its product. Null, or left out, covers the whole product; send null to take a narrowing off again. For several at once, send `matches`","anyOf":[{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},{"type":"null"}]},"matches":{"examples":[["com","net","org"]],"description":"Narrows the offer to any of these: several domain endings, countries or plans in one promotion. Send this or `match`, not both; null takes the narrowing off again","anyOf":[{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"}},{"type":"null"}]},"term":{"description":"Narrows a number offer to one rental length. Null, or left out, covers every length","anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}]},"kind":{"type":"string","enum":["fixed","percent","amount"],"description":"`fixed` is the promotional price itself; `percent` takes a share off the normal price; `amount` takes a fixed sum off it"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Minor units of the list's currency for `fixed` and `amount`; basis points for `percent` (2500 is 25% off)"},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"When the offer starts"},"endsAt":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"],"description":"When it stops. A purchase at or after this moment pays the normal price"},"code":{"description":"The coupon code an order has to send. Null, or left out, and everyone on the list gets the offer without asking. A code is never handed out twice, even after the offer ends","anyOf":[{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},{"type":"null"}]},"maxUses":{"examples":[100],"description":"How many times it may be used in all. Null, or left out, for no limit","anyOf":[{"type":"integer","minimum":1,"maximum":1000000},{"type":"null"}]},"maxPerCustomer":{"examples":[1],"description":"How many times one customer may use it. Null, or left out, for no limit","anyOf":[{"type":"integer","minimum":1,"maximum":1000000},{"type":"null"}]},"applies":{"default":"new","type":"string","enum":["new","renew","both"],"description":"`new` is first purchases only, which is what an introductory offer means; `renew` is renewals only; `both` is every purchase, a restore included"},"allowBelowCost":{"default":false,"type":"boolean","description":"Lets the promotional price sit under what you pay for the item"},"id":{"description":"The offer being changed, so its own dates and coupon are not counted twice","type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]}},"required":["name","product","kind","value","startsAt","endsAt"]}}}},"responses":{"200":{"description":"What the offer would do to the prices customers on its list are charged","content":{"application/json":{"schema":{"description":"What the offer would do to the prices customers on its list are charged","type":"object","properties":{"customers":{"type":"integer","examples":[3],"description":"How many customers are on the offer's list"},"items":{"type":"integer","examples":[12],"description":"How many active domains, licences and numbers those customers hold"},"belowCost":{"type":"integer","examples":[0],"description":"How many of the items in `data` would sell under what you pay"},"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"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"},"normal":{"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"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"},"normalPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer would pay for one unit with no promotion, in `currency`. The same as `price` when none applied"},"discount":{"type":"integer","minimum":0,"examples":[1440],"description":"What a promotion took off `normalPrice`. Zero when none applied"},"promotion":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"code":{"examples":["LAUNCH25"],"description":"The coupon code this promotion needs. Null when everyone on the list gets it","type":["string","null"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-01T00:00:00.000Z"],"description":"When the promotional price stops applying"}},"required":["id","code","endsAt"],"additionalProperties":false},{"type":"null"}],"description":"The promotion that set the price. Null when none applied"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored","normalPrice","discount","promotion"],"additionalProperties":false,"description":"What the customer pays for one unit now"},"promoted":{"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"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"},"normalPrice":{"type":"integer","minimum":0,"examples":[1440],"description":"What the customer would pay for one unit with no promotion, in `currency`. The same as `price` when none applied"},"discount":{"type":"integer","minimum":0,"examples":[1440],"description":"What a promotion took off `normalPrice`. Zero when none applied"},"promotion":{"anyOf":[{"type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"code":{"examples":["LAUNCH25"],"description":"The coupon code this promotion needs. Null when everyone on the list gets it","type":["string","null"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-11-01T00:00:00.000Z"],"description":"When the promotional price stops applying"}},"required":["id","code","endsAt"],"additionalProperties":false},{"type":"null"}],"description":"The promotion that set the price. Null when none applied"}},"required":["cost","price","currency","priceUsd","ruleId","level","floored","normalPrice","discount","promotion"],"additionalProperties":false,"description":"What they would pay on the offer"}},"required":["type","id","name","customerId","cost","normal","promoted"],"additionalProperties":false}}},"required":["customers","items","belowCost","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 `invalid_dates`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `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":"invalid_dates","message":"A contract price must end after it starts","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/promotions/{id}":{"get":{"operationId":"getPromotion","summary":"Get a promotion","tags":["Promotions"],"description":"One offer, with how many times it has been used and what it has taken off.","parameters":[{"schema":{"type":"string"},"example":"prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Launch offer on .com"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The list the offer belongs to. Null when it covers every list"},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"match":{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},{"type":"null"}],"description":"What it is narrowed to within its product, or the first of `matches` when it names several. Null for all of it"},"matches":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"}},{"type":"null"}],"examples":[["com","net","org"]],"description":"Everything it is narrowed to: one or several. Null for all of it"},"term":{"anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}],"description":"The rental length it is narrowed to. Null for every length"},"applies":{"type":"string","enum":["new","renew","both"],"description":"`new` is first purchases only, which is what an introductory offer means; `renew` is renewals only; `both` is every purchase, a restore included"},"kind":{"type":"string","enum":["fixed","percent","amount"],"description":"`fixed` is the promotional price itself; `percent` takes a share off the normal price; `amount` takes a fixed sum off it"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Minor units of the list's currency for `fixed` and `amount`; basis points for `percent` (2500 is 25% off)"},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"]},"code":{"anyOf":[{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},{"type":"null"}],"description":"The coupon code an order has to send. Null when everyone on the list gets the offer"},"maxUses":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[100],"description":"How many times it may be used in all. Null for no limit"},"maxPerCustomer":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[1],"description":"How many times one customer may use it. Null for no limit"},"allowBelowCost":{"type":"boolean","description":"Lets the promotional price sit under what you pay for the item"},"status":{"type":"string","enum":["scheduled","live","ended","used_up"],"description":"`scheduled` has not started, `live` is running now, `ended` is past its dates and `used_up` has been used as often as it allows"},"uses":{"type":"integer","examples":[12],"description":"How many times it has been used"},"discountUsd":{"type":"integer","minimum":0,"examples":[1440],"description":"What it has taken off in all, in US cents"},"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","priceListId","product","match","matches","term","applies","kind","value","startsAt","endsAt","code","maxUses","maxPerCustomer","allowBelowCost","status","uses","discountUsd","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"updatePromotion","summary":"Update a promotion","tags":["Promotions"],"description":"Send only what changes. Purchases already made keep the price they were made at, and the uses already claimed stay claimed.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80,"examples":["Launch offer on .com"]},"priceListId":{"description":"The list the offer belongs to. Null, or left out, covers every list","anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"match":{"description":"Narrows the offer within its product. Null, or left out, covers the whole product; send null to take a narrowing off again. For several at once, send `matches`","anyOf":[{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},{"type":"null"}]},"matches":{"examples":[["com","net","org"]],"description":"Narrows the offer to any of these: several domain endings, countries or plans in one promotion. Send this or `match`, not both; null takes the narrowing off again","anyOf":[{"minItems":1,"maxItems":50,"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"}},{"type":"null"}]},"term":{"description":"Narrows a number offer to one rental length. Null, or left out, covers every length","anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}]},"kind":{"type":"string","enum":["fixed","percent","amount"],"description":"`fixed` is the promotional price itself; `percent` takes a share off the normal price; `amount` takes a fixed sum off it"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Minor units of the list's currency for `fixed` and `amount`; basis points for `percent` (2500 is 25% off)"},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"When the offer starts"},"endsAt":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"],"description":"When it stops. A purchase at or after this moment pays the normal price"},"code":{"description":"The coupon code an order has to send. Null, or left out, and everyone on the list gets the offer without asking. A code is never handed out twice, even after the offer ends","anyOf":[{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},{"type":"null"}]},"maxUses":{"examples":[100],"description":"How many times it may be used in all. Null, or left out, for no limit","anyOf":[{"type":"integer","minimum":1,"maximum":1000000},{"type":"null"}]},"maxPerCustomer":{"examples":[1],"description":"How many times one customer may use it. Null, or left out, for no limit","anyOf":[{"type":"integer","minimum":1,"maximum":1000000},{"type":"null"}]},"applies":{"type":"string","enum":["new","renew","both"],"description":"`new` is first purchases only, which is what an introductory offer means; `renew` is renewals only; `both` is every purchase, a restore included"},"allowBelowCost":{"type":"boolean","description":"Lets the promotional price sit under what you pay for the item"}}}}}},"parameters":[{"schema":{"type":"string"},"example":"prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Launch offer on .com"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"The list the offer belongs to. Null when it covers every list"},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"match":{"anyOf":[{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"},{"type":"null"}],"description":"What it is narrowed to within its product, or the first of `matches` when it names several. Null for all of it"},"matches":{"anyOf":[{"type":"array","items":{"type":"string","minLength":1,"maxLength":80,"examples":["com"],"description":"A domain ending (`com`), a country code (`US`) or a licence plan id"}},{"type":"null"}],"examples":[["com","net","org"]],"description":"Everything it is narrowed to: one or several. Null for all of it"},"term":{"anyOf":[{"type":"string","minLength":1,"maxLength":20,"examples":["30d"]},{"type":"null"}],"description":"The rental length it is narrowed to. Null for every length"},"applies":{"type":"string","enum":["new","renew","both"],"description":"`new` is first purchases only, which is what an introductory offer means; `renew` is renewals only; `both` is every purchase, a restore included"},"kind":{"type":"string","enum":["fixed","percent","amount"],"description":"`fixed` is the promotional price itself; `percent` takes a share off the normal price; `amount` takes a fixed sum off it"},"value":{"type":"integer","minimum":0,"maximum":100000000,"examples":[2500],"description":"Minor units of the list's currency for `fixed` and `amount`; basis points for `percent` (2500 is 25% off)"},"startsAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"endsAt":{"type":"string","format":"date-time","examples":["2026-12-01T00:00:00.000Z"]},"code":{"anyOf":[{"type":"string","minLength":1,"maxLength":40,"examples":["LAUNCH25"],"description":"A coupon code, unlocking the promotion it belongs to"},{"type":"null"}],"description":"The coupon code an order has to send. Null when everyone on the list gets the offer"},"maxUses":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[100],"description":"How many times it may be used in all. Null for no limit"},"maxPerCustomer":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[1],"description":"How many times one customer may use it. Null for no limit"},"allowBelowCost":{"type":"boolean","description":"Lets the promotional price sit under what you pay for the item"},"status":{"type":"string","enum":["scheduled","live","ended","used_up"],"description":"`scheduled` has not started, `live` is running now, `ended` is past its dates and `used_up` has been used as often as it allows"},"uses":{"type":"integer","examples":[12],"description":"How many times it has been used"},"discountUsd":{"type":"integer","minimum":0,"examples":[1440],"description":"What it has taken off in all, in US cents"},"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","priceListId","product","match","matches","term","applies","kind","value","startsAt","endsAt","code","maxUses","maxPerCustomer","allowBelowCost","status","uses","discountUsd","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `duplicate_coupon` or `too_many_promotions`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `duplicate_coupon` or `too_many_promotions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"duplicate_coupon","message":"That coupon code is already in use","requestId":"req-4f"}},"example2":{"value":{"error":"too_many_promotions","message":"An account holds at most 200 promotions","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `promotion_below_cost` or `invalid_dates`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `promotion_below_cost` 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"]},"examples":{"example1":{"value":{"error":"promotion_below_cost","message":"This promotion would sell under what you pay; allow selling below cost to run it anyway","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_dates","message":"A contract price must end after it starts","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"deletePromotion","summary":"Delete a promotion","tags":["Promotions"],"description":"Stops the offer and frees its coupon code. Sales made on it keep the price they were made at. To end an offer early without losing the record of it, move its `endsAt` instead.","parameters":[{"schema":{"type":"string"},"example":"prm_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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"]},"discounts":{"description":"Money off, before tax, taken after the sales","maxItems":20,"type":"array","items":{"type":"object","properties":{"saleId":{"description":"Off this one sale line. Unset, off the sales as a whole","type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"percentBps":{"examples":[1000],"description":"A share of what it comes off, in basis points: 1000 is 10%","type":"integer","minimum":1,"maximum":10000},"amount":{"examples":[500],"description":"A flat amount off, in the invoice currency","type":"integer","exclusiveMinimum":0},"description":{"description":"Shown on the invoice. Unset, one is written for you","type":"string","minLength":1,"maxLength":200}}}}},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a discount line, whose `total` is under zero"},"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","examples":[1439],"description":"Minor units of the invoice's currency. Under zero on a credit"},"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line: one entry per matched tax rule component. Empty on an invoice priced with the flat `taxBps` or with no tax at all"},"reverseCharge":{"anyOf":[{"type":"object","properties":{"note":{"type":"string"},"sellerTaxId":{"type":["string","null"]},"customerTaxId":{"type":["string","null"]}},"required":["note","sellerTaxId","customerTaxId"],"additionalProperties":false},{"type":"null"}],"description":"Set when the matched tax rule reverse-charges this invoice: `tax` is `0` and this is the legal note and both parties' tax numbers as they stood at issue"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void","credited"],"description":"`credited` was corrected in full by credit notes and asks for nothing"},"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"]},"credited":{"type":"integer","minimum":0,"examples":[2878],"description":"What credit notes against this invoice come to. `0` when there are none"},"paidAmount":{"type":"integer","minimum":0,"examples":[2878],"description":"Collected so far via payments applied to this invoice. `0` until the first one"},"amountDue":{"type":"integer","minimum":0,"examples":[2878],"description":"What is still owed: `total` less `credited` and `paidAmount`, and `0` on one that is paid, void or credited in full"},"creditedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[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"},"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 raised this invoice"},"voidedBy":{"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 voided this invoice. Null unless `status` is `void`"},"paidBy":{"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 recorded this invoice as paid. Null unless `status` is `paid` through that path"},"sharedBy":{"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 last shared this invoice. Null until it has ever been shared"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","taxLines","reverseCharge","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","credited","paidAmount","amountDue","creditedAt","issuer","actor","voidedBy","paidBy","sharedBy"],"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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`, `discount_too_large`, `invalid_discount`, 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`, `discount_too_large`, `invalid_discount`, 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"},"details":{"type":"object","description":"Present when `error` is `discount_too_large`, carrying `maximum`.","properties":{"maximum":{"type":"number","description":"What was actually left for this discount to take off"}}}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"nothing_to_invoice","message":"This customer has no sales waiting to be invoiced","requestId":"req-4f"}},"example2":{"value":{"error":"mixed_currencies","message":"These sales are in more than one currency; invoice one at a time","requestId":"req-4f"}},"example3":{"value":{"error":"sale_unavailable","message":"One of these sales is not this customer's or is already invoiced","requestId":"req-4f"}},"example4":{"value":{"error":"discount_too_large","message":"This discount is larger than what is left to take it off","requestId":"req-4f"}},"example5":{"value":{"error":"invalid_discount","message":"A discount names a sale that is not on this invoice","requestId":"req-4f"}},"example6":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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","credited"]},"in":"query","name":"status","required":false,"description":"`credited` was corrected in full by credit notes and asks for nothing"},{"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a discount line, whose `total` is under zero"},"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","examples":[1439],"description":"Minor units of the invoice's currency. Under zero on a credit"},"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line: one entry per matched tax rule component. Empty on an invoice priced with the flat `taxBps` or with no tax at all"},"reverseCharge":{"anyOf":[{"type":"object","properties":{"note":{"type":"string"},"sellerTaxId":{"type":["string","null"]},"customerTaxId":{"type":["string","null"]}},"required":["note","sellerTaxId","customerTaxId"],"additionalProperties":false},{"type":"null"}],"description":"Set when the matched tax rule reverse-charges this invoice: `tax` is `0` and this is the legal note and both parties' tax numbers as they stood at issue"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void","credited"],"description":"`credited` was corrected in full by credit notes and asks for nothing"},"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"]},"credited":{"type":"integer","minimum":0,"examples":[2878],"description":"What credit notes against this invoice come to. `0` when there are none"},"paidAmount":{"type":"integer","minimum":0,"examples":[2878],"description":"Collected so far via payments applied to this invoice. `0` until the first one"},"amountDue":{"type":"integer","minimum":0,"examples":[2878],"description":"What is still owed: `total` less `credited` and `paidAmount`, and `0` on one that is paid, void or credited in full"},"creditedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[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"},"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 raised this invoice"},"voidedBy":{"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 voided this invoice. Null unless `status` is `void`"},"paidBy":{"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 recorded this invoice as paid. Null unless `status` is `paid` through that path"},"sharedBy":{"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 last shared this invoice. Null until it has ever been shared"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","taxLines","reverseCharge","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","credited","paidAmount","amountDue","creditedAt","issuer","actor","voidedBy","paidBy","sharedBy"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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. Every figure but the counts is net of the credit notes issued against those invoices.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"open":{"type":"integer","minimum":0,"examples":[2878],"description":"On invoices waiting to be paid, overdue ones included. Net of what has been credited"},"overdue":{"type":"integer","minimum":0,"examples":[0],"description":"The part of `open` past its due date. Net of what has been credited"},"paid":{"type":"integer","minimum":0,"examples":[2878],"description":"On invoices you marked paid. Net of what has been credited"},"credited":{"type":"integer","minimum":0,"examples":[0],"description":"What credit notes have taken off their invoices, void invoices excluded. The one figure a fully credited invoice appears in"},"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","credited","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a discount line, whose `total` is under zero"},"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","examples":[1439],"description":"Minor units of the invoice's currency. Under zero on a credit"},"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line: one entry per matched tax rule component. Empty on an invoice priced with the flat `taxBps` or with no tax at all"},"reverseCharge":{"anyOf":[{"type":"object","properties":{"note":{"type":"string"},"sellerTaxId":{"type":["string","null"]},"customerTaxId":{"type":["string","null"]}},"required":["note","sellerTaxId","customerTaxId"],"additionalProperties":false},{"type":"null"}],"description":"Set when the matched tax rule reverse-charges this invoice: `tax` is `0` and this is the legal note and both parties' tax numbers as they stood at issue"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void","credited"],"description":"`credited` was corrected in full by credit notes and asks for nothing"},"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"]},"credited":{"type":"integer","minimum":0,"examples":[2878],"description":"What credit notes against this invoice come to. `0` when there are none"},"paidAmount":{"type":"integer","minimum":0,"examples":[2878],"description":"Collected so far via payments applied to this invoice. `0` until the first one"},"amountDue":{"type":"integer","minimum":0,"examples":[2878],"description":"What is still owed: `total` less `credited` and `paidAmount`, and `0` on one that is paid, void or credited in full"},"creditedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[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"},"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 raised this invoice"},"voidedBy":{"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 voided this invoice. Null unless `status` is `void`"},"paidBy":{"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 recorded this invoice as paid. Null unless `status` is `paid` through that path"},"sharedBy":{"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 last shared this invoice. Null until it has ever been shared"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","taxLines","reverseCharge","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","credited","paidAmount","amountDue","creditedAt","issuer","actor","voidedBy","paidBy","sharedBy"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a discount line, whose `total` is under zero"},"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","examples":[1439],"description":"Minor units of the invoice's currency. Under zero on a credit"},"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line: one entry per matched tax rule component. Empty on an invoice priced with the flat `taxBps` or with no tax at all"},"reverseCharge":{"anyOf":[{"type":"object","properties":{"note":{"type":"string"},"sellerTaxId":{"type":["string","null"]},"customerTaxId":{"type":["string","null"]}},"required":["note","sellerTaxId","customerTaxId"],"additionalProperties":false},{"type":"null"}],"description":"Set when the matched tax rule reverse-charges this invoice: `tax` is `0` and this is the legal note and both parties' tax numbers as they stood at issue"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void","credited"],"description":"`credited` was corrected in full by credit notes and asks for nothing"},"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"]},"credited":{"type":"integer","minimum":0,"examples":[2878],"description":"What credit notes against this invoice come to. `0` when there are none"},"paidAmount":{"type":"integer","minimum":0,"examples":[2878],"description":"Collected so far via payments applied to this invoice. `0` until the first one"},"amountDue":{"type":"integer","minimum":0,"examples":[2878],"description":"What is still owed: `total` less `credited` and `paidAmount`, and `0` on one that is paid, void or credited in full"},"creditedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[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"},"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 raised this invoice"},"voidedBy":{"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 voided this invoice. Null unless `status` is `void`"},"paidBy":{"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 recorded this invoice as paid. Null unless `status` is `paid` through that path"},"sharedBy":{"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 last shared this invoice. Null until it has ever been shared"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","taxLines","reverseCharge","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","credited","paidAmount","amountDue","creditedAt","issuer","actor","voidedBy","paidBy","sharedBy"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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, and neither can one that already carries a credit note: credit the rest of that one instead.","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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a discount line, whose `total` is under zero"},"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","examples":[1439],"description":"Minor units of the invoice's currency. Under zero on a credit"},"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line: one entry per matched tax rule component. Empty on an invoice priced with the flat `taxBps` or with no tax at all"},"reverseCharge":{"anyOf":[{"type":"object","properties":{"note":{"type":"string"},"sellerTaxId":{"type":["string","null"]},"customerTaxId":{"type":["string","null"]}},"required":["note","sellerTaxId","customerTaxId"],"additionalProperties":false},{"type":"null"}],"description":"Set when the matched tax rule reverse-charges this invoice: `tax` is `0` and this is the legal note and both parties' tax numbers as they stood at issue"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void","credited"],"description":"`credited` was corrected in full by credit notes and asks for nothing"},"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"]},"credited":{"type":"integer","minimum":0,"examples":[2878],"description":"What credit notes against this invoice come to. `0` when there are none"},"paidAmount":{"type":"integer","minimum":0,"examples":[2878],"description":"Collected so far via payments applied to this invoice. `0` until the first one"},"amountDue":{"type":"integer","minimum":0,"examples":[2878],"description":"What is still owed: `total` less `credited` and `paidAmount`, and `0` on one that is paid, void or credited in full"},"creditedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[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"},"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 raised this invoice"},"voidedBy":{"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 voided this invoice. Null unless `status` is `void`"},"paidBy":{"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 recorded this invoice as paid. Null unless `status` is `paid` through that path"},"sharedBy":{"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 last shared this invoice. Null until it has ever been shared"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","taxLines","reverseCharge","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","credited","paidAmount","amountDue","creditedAt","issuer","actor","voidedBy","paidBy","sharedBy"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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` or `invoice_not_voidable`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `invoice_not_open` or `invoice_not_voidable`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"invoice_not_open","message":"This invoice is already paid","requestId":"req-4f"}},"example2":{"value":{"error":"invoice_not_voidable","message":"This invoice has a credit note against it and has to stand; credit the rest of it instead","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/credit-notes":{"post":{"operationId":"createCreditNote","summary":"Issue a credit note","tags":["Credit notes"],"description":"Corrects an invoice already issued, by named lines or by a flat amount, instead of editing it: an invoice is never rewritten once sent. A fully credited open invoice moves to `credited`; a paid invoice stays `paid`. Send an Idempotency-Key header so a retry can never credit twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500,"examples":["Customer cancelled a seat"]},"lines":{"description":"Credit these invoice lines, by the sale each one bills","minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"saleId":{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"amount":{"examples":[500],"description":"What to credit on this line, before tax. Unset credits all that is left","type":"integer","exclusiveMinimum":0}},"required":["saleId"]}},"amount":{"examples":[500],"description":"A flat amount off the invoice, before tax, instead of named lines","type":"integer","exclusiveMinimum":0}},"required":["reason"]}}}},"parameters":[{"schema":{"type":"string"},"example":"inv_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":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["crn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["CN-0001"],"description":"Counts up from CN-0001 across your account, with no gaps"},"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"invoiceNumber":{"type":"string","examples":["INV-0001"]},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the credit note"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a credit taken as a flat amount rather than against named lines"},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2]},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[1439],"description":"What is credited on this line, before tax"}},"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":"Copied from the invoice's rate. Null when the invoice carried no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What this credit note comes to: `subtotal` plus `tax`"},"reason":{"type":"string","examples":["Customer cancelled a seat"]},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"shared":{"type":"boolean","description":"True once `POST /credit-notes/{id}/share` has made a public link for this credit note, false again once revoked. The token itself is never in this response or the list"},"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":"The account as it billed the invoice this credit note corrects"}},"required":["id","number","invoiceId","invoiceNumber","customerId","currency","lines","subtotal","taxBps","tax","total","reason","issuedAt","shared","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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_creditable`, `credit_conflict`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `invoice_not_creditable`, `credit_conflict`, 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"]},"examples":{"example1":{"value":{"error":"invoice_not_creditable","message":"This invoice is void, already credited in full, or has nothing left to credit","requestId":"req-4f"}},"example2":{"value":{"error":"credit_conflict","message":"Another credit note for this invoice was issued at the same time; read the invoice and try again","requestId":"req-4f"}},"example3":{"value":{"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 `credit_too_large`, `credit_line_unknown`, `invalid_credit`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `credit_too_large`, `credit_line_unknown`, `invalid_credit`, 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"},"details":{"type":"object","description":"Present when `error` is `credit_too_large`, carrying `creditable`.","properties":{"creditable":{"type":"number","description":"What is actually left to credit, before tax"}}}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"credit_too_large","message":"This credits more than is left to credit","requestId":"req-4f"}},"example2":{"value":{"error":"credit_line_unknown","message":"This invoice has no such line","requestId":"req-4f"}},"example3":{"value":{"error":"invalid_credit","message":"A credit note needs a reason, and exactly one of lines or amount","requestId":"req-4f"}},"example4":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"listInvoiceCreditNotes","summary":"List credit notes against an invoice","tags":["Credit notes"],"description":"Newest first, at most 200.","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":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["crn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["CN-0001"],"description":"Counts up from CN-0001 across your account, with no gaps"},"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"invoiceNumber":{"type":"string","examples":["INV-0001"]},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the credit note"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a credit taken as a flat amount rather than against named lines"},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2]},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[1439],"description":"What is credited on this line, before tax"}},"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":"Copied from the invoice's rate. Null when the invoice carried no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What this credit note comes to: `subtotal` plus `tax`"},"reason":{"type":"string","examples":["Customer cancelled a seat"]},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"shared":{"type":"boolean","description":"True once `POST /credit-notes/{id}/share` has made a public link for this credit note, false again once revoked. The token itself is never in this response or the list"},"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":"The account as it billed the invoice this credit note corrects"}},"required":["id","number","invoiceId","invoiceNumber","customerId","currency","lines","subtotal","taxBps","tax","total","reason","issuedAt","shared","issuer"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/creditable":{"get":{"operationId":"getInvoiceCreditable","summary":"See what is left to credit on an invoice","tags":["Credit notes"],"description":"What is left uncredited on this invoice, line by line and in total. A void invoice answers with everything at zero.","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":{"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"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"}]},"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]},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[2878],"description":"The line's own total on the invoice"},"credited":{"type":"integer","minimum":0,"examples":[2878],"description":"What has already been credited on this line"},"creditable":{"type":"integer","minimum":0,"examples":[2878],"description":"What is left to credit on this line"}},"required":["saleId","description","quantity","unitPrice","total","credited","creditable"],"additionalProperties":false}},"subtotal":{"type":"integer","minimum":0,"examples":[2878],"description":"What is left uncredited, before tax"},"tax":{"type":"integer","minimum":0,"examples":[2878],"description":"The tax on what is left uncredited"},"total":{"type":"integer","minimum":0,"examples":[2878],"description":"What is left uncredited, before tax and after it, added together"}},"required":["currency","taxBps","lines","subtotal","tax","total"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/credit-notes":{"get":{"operationId":"listCreditNotes","summary":"List credit notes","tags":["Credit notes"],"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"},"example":"inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"query","name":"invoiceId","required":false},{"schema":{"type":"string","minLength":1,"maxLength":100},"in":"query","name":"q","required":false,"description":"Text to look for in the credit note number, or in the customer's name or email"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["crn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["CN-0001"],"description":"Counts up from CN-0001 across your account, with no gaps"},"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"invoiceNumber":{"type":"string","examples":["INV-0001"]},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the credit note"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a credit taken as a flat amount rather than against named lines"},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2]},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[1439],"description":"What is credited on this line, before tax"}},"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":"Copied from the invoice's rate. Null when the invoice carried no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What this credit note comes to: `subtotal` plus `tax`"},"reason":{"type":"string","examples":["Customer cancelled a seat"]},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"shared":{"type":"boolean","description":"True once `POST /credit-notes/{id}/share` has made a public link for this credit note, false again once revoked. The token itself is never in this response or the list"},"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":"The account as it billed the invoice this credit note corrects"}},"required":["id","number","invoiceId","invoiceNumber","customerId","currency","lines","subtotal","taxBps","tax","total","reason","issuedAt","shared","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/credit-notes/{id}":{"get":{"operationId":"getCreditNote","summary":"Get a credit note","tags":["Credit notes"],"parameters":[{"schema":{"type":"string"},"example":"crn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["crn_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["CN-0001"],"description":"Counts up from CN-0001 across your account, with no gaps"},"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"invoiceNumber":{"type":"string","examples":["INV-0001"]},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the credit note"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a credit taken as a flat amount rather than against named lines"},"description":{"type":"string","examples":["northwind-telecom.com, 2 years"]},"quantity":{"type":"integer","examples":[2]},"unitPrice":{"type":"integer","minimum":0,"examples":[1439],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[1439],"description":"What is credited on this line, before tax"}},"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":"Copied from the invoice's rate. Null when the invoice carried no tax"},"tax":{"type":"integer","minimum":0,"examples":[576],"description":"Minor units of the invoice's currency"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What this credit note comes to: `subtotal` plus `tax`"},"reason":{"type":"string","examples":["Customer cancelled a seat"]},"issuedAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"shared":{"type":"boolean","description":"True once `POST /credit-notes/{id}/share` has made a public link for this credit note, false again once revoked. The token itself is never in this response or the list"},"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":"The account as it billed the invoice this credit note corrects"}},"required":["id","number","invoiceId","invoiceNumber","customerId","currency","lines","subtotal","taxBps","tax","total","reason","issuedAt","shared","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/credit-notes/{id}/share":{"post":{"operationId":"shareCreditNote","summary":"Share a credit note","tags":["Credit notes"],"description":"Creates a public, read-only link to this credit note that needs no API key: `GET /public/credit-notes/{token}`. Calling this again returns the same token, so the share button is safe to press twice.","parameters":[{"schema":{"type":"string"},"example":"crn_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/credit-notes/{token}`. Unguessable; treat it like a capability on this one credit note, 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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"revokeCreditNoteShare","summary":"Revoke a credit note link","tags":["Credit notes"],"description":"The public link stops working at once. A credit note 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":"crn_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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Payments"],"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. Every invoiced figure is net of the credit notes issued against those invoices.","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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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. Net of what has been credited"},"overdue":{"type":"integer","minimum":0,"examples":[0],"description":"The part of `open` past its due date. Net of what has been credited"},"paid":{"type":"integer","minimum":0,"examples":[2878],"description":"On invoices you marked paid. Net of what has been credited"},"credited":{"type":"integer","minimum":0,"examples":[0],"description":"What credit notes have taken off this customer's invoices, void ones excluded. The one figure a fully credited invoice appears in"},"credit":{"type":"integer","minimum":0,"examples":[0],"description":"Payments not yet applied to an invoice, less refunds already taken out of them: money this customer can have applied to their next invoice, or back"}},"required":["currency","uninvoiced","open","overdue","paid","credited","credit"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/payments":{"post":{"operationId":"recordPayment","summary":"Record a payment","tags":["Payments"],"description":"Records money received from this customer. Applied to the invoices you name, each for the amount you give it, in that order, or else to their oldest open invoices in the same currency, each in full. Anything left over stays as credit on the customer's account. 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 record the payment twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"examples":[2878]},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"date":{"description":"When the money arrived. Unset, now","type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"method":{"type":"string","enum":["bank_transfer","cash","card","other"],"description":"How the money moved, outside this platform"},"reference":{"examples":["Bank transfer #1042"],"type":"string","minLength":1,"maxLength":200},"applyToInvoices":{"description":"Apply to these invoices, each for its own amount, in this order. These amounts must not add up to more than `amount`, and each is still capped by that invoice's own due. Unset, applied oldest-open-first in `currency`, each in full","minItems":1,"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"amount":{"type":"integer","exclusiveMinimum":0,"examples":[1000]}},"required":["invoiceId","amount"]}}},"required":["amount","currency","method"]}}}},"parameters":[{"schema":{"type":"string"},"example":"cus_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":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["pmt_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["PMT-0001"],"description":"Counts up from PMT-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"date":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"When the money arrived, as you recorded it"},"method":{"type":"string","enum":["bank_transfer","cash","card","other"],"description":"How the money moved, outside this platform"},"reference":{"examples":[null],"type":["string","null"]},"allocations":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"invoiceNumber":{"type":"string","examples":["INV-0001"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"}},"required":["invoiceId","invoiceNumber","amount"],"additionalProperties":false}},"unallocated":{"type":"integer","minimum":0,"examples":[2878],"description":"`amount` less what `allocations` adds up to: the credit this payment left on the customer's account"},"shared":{"type":"boolean","description":"True once `POST /payments/{id}/share` has made a public receipt link, false again once revoked"},"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"}]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","number","customerId","amount","currency","date","method","reference","allocations","unallocated","shared","issuer","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `allocation_too_large`, `invoice_not_payable`, or `idempotency_in_progress`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `allocation_too_large`, `invoice_not_payable`, 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"]},"examples":{"example1":{"value":{"error":"allocation_too_large","message":"The invoices named add up to more than the payment amount","requestId":"req-4f"}},"example2":{"value":{"error":"invoice_not_payable","message":"This invoice cannot take this payment","requestId":"req-4f"}},"example3":{"value":{"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 `invalid_payment` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_payment` 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"]},"examples":{"example1":{"value":{"error":"invalid_payment","message":"A payment must be above zero","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"listCustomerPayments","summary":"List a customer's payments","tags":["Payments"],"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":"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":["pmt_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["PMT-0001"],"description":"Counts up from PMT-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"date":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"When the money arrived, as you recorded it"},"method":{"type":"string","enum":["bank_transfer","cash","card","other"],"description":"How the money moved, outside this platform"},"reference":{"examples":[null],"type":["string","null"]},"allocations":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"invoiceNumber":{"type":"string","examples":["INV-0001"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"}},"required":["invoiceId","invoiceNumber","amount"],"additionalProperties":false}},"unallocated":{"type":"integer","minimum":0,"examples":[2878],"description":"`amount` less what `allocations` adds up to: the credit this payment left on the customer's account"},"shared":{"type":"boolean","description":"True once `POST /payments/{id}/share` has made a public receipt link, false again once revoked"},"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"}]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","number","customerId","amount","currency","date","method","reference","allocations","unallocated","shared","issuer","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"}}}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/payments/{id}":{"get":{"operationId":"getPayment","summary":"Get a payment","tags":["Payments"],"parameters":[{"schema":{"type":"string"},"example":"pmt_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["pmt_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["PMT-0001"],"description":"Counts up from PMT-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"date":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"When the money arrived, as you recorded it"},"method":{"type":"string","enum":["bank_transfer","cash","card","other"],"description":"How the money moved, outside this platform"},"reference":{"examples":[null],"type":["string","null"]},"allocations":{"type":"array","items":{"type":"object","properties":{"invoiceId":{"type":"string","examples":["inv_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"invoiceNumber":{"type":"string","examples":["INV-0001"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"}},"required":["invoiceId","invoiceNumber","amount"],"additionalProperties":false}},"unallocated":{"type":"integer","minimum":0,"examples":[2878],"description":"`amount` less what `allocations` adds up to: the credit this payment left on the customer's account"},"shared":{"type":"boolean","description":"True once `POST /payments/{id}/share` has made a public receipt link, false again once revoked"},"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"}]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","number","customerId","amount","currency","date","method","reference","allocations","unallocated","shared","issuer","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/payments/{id}/share":{"post":{"operationId":"sharePayment","summary":"Share a payment receipt","tags":["Payments"],"description":"Creates a public, read-only receipt link for this payment that needs no API key: `GET /public/payments/{token}`. Calling this again returns the same token, so the share button is safe to press twice.","parameters":[{"schema":{"type":"string"},"example":"pmt_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/payments/{token}`. Unguessable; treat it like a capability on this one payment, 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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"revokePaymentShare","summary":"Revoke a payment receipt link","tags":["Payments"],"description":"The public receipt stops working at once. A payment with no link also answers 204: there is nothing to revoke.","parameters":[{"schema":{"type":"string"},"example":"pmt_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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/refunds":{"post":{"operationId":"recordRefund","summary":"Record a refund","tags":["Payments"],"description":"Records money handed back out of credit this customer holds with you. Refused when it is more than they have. 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 record the refund twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"examples":[500]},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"method":{"type":"string","enum":["bank_transfer","cash","card","other"],"description":"How the money moved, outside this platform"},"reference":{"examples":["Bank transfer #1043"],"type":"string","minLength":1,"maxLength":200}},"required":["amount","currency","method"]}}}},"parameters":[{"schema":{"type":"string"},"example":"cus_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":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["rfd_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["RFD-0001"],"description":"Counts up from RFD-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"method":{"type":"string","enum":["bank_transfer","cash","card","other"],"description":"How the money moved, outside this platform"},"reference":{"examples":[null],"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","number","customerId","amount","currency","method","reference","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `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 `invalid_refund`, `insufficient_credit`, or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `invalid_refund`, `insufficient_credit`, 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"},"details":{"type":"object","description":"Present when `error` is `insufficient_credit`, carrying `available`.","properties":{"available":{"type":"number","description":"What the customer actually holds in this currency"}}}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"invalid_refund","message":"A refund must be above zero","requestId":"req-4f"}},"example2":{"value":{"error":"insufficient_credit","message":"This customer does not hold enough credit for this refund","requestId":"req-4f"}},"example3":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"listCustomerRefunds","summary":"List a customer's refunds","tags":["Payments"],"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":"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":["rfd_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"number":{"type":"string","examples":["RFD-0001"],"description":"Counts up from RFD-0001 across your account, with no gaps"},"customerId":{"type":"string","examples":["cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"amount":{"type":"integer","minimum":0,"examples":[2878],"description":"Minor units of the invoice's currency"},"currency":{"type":"string","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"method":{"type":"string","enum":["bank_transfer","cash","card","other"],"description":"How the money moved, outside this platform"},"reference":{"examples":[null],"type":["string","null"]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","number","customerId","amount","currency","method","reference","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"}}}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/apply-credit":{"post":{"operationId":"applyCreditToInvoice","summary":"Apply a customer's credit to an invoice","tags":["Invoices"],"description":"Draws on the customer's unallocated payment credit, oldest payment first, to pay down this invoice as far as the credit in the invoice's own currency goes. Refused when the invoice is not open, or there is no credit in that currency.","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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"The currency of every amount on the invoice"},"lines":{"type":"array","items":{"type":"object","properties":{"saleId":{"anyOf":[{"type":"string","examples":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Null on a discount line, whose `total` is under zero"},"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","examples":[1439],"description":"Minor units of the invoice's currency. Under zero on a credit"},"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the invoice's currency. Under zero on a credit"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line: one entry per matched tax rule component. Empty on an invoice priced with the flat `taxBps` or with no tax at all"},"reverseCharge":{"anyOf":[{"type":"object","properties":{"note":{"type":"string"},"sellerTaxId":{"type":["string","null"]},"customerTaxId":{"type":["string","null"]}},"required":["note","sellerTaxId","customerTaxId"],"additionalProperties":false},{"type":"null"}],"description":"Set when the matched tax rule reverse-charges this invoice: `tax` is `0` and this is the legal note and both parties' tax numbers as they stood at issue"},"total":{"type":"integer","minimum":0,"examples":[3454],"description":"What the customer owes: `subtotal` plus `tax`"},"status":{"type":"string","enum":["open","paid","void","credited"],"description":"`credited` was corrected in full by credit notes and asks for nothing"},"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"]},"credited":{"type":"integer","minimum":0,"examples":[2878],"description":"What credit notes against this invoice come to. `0` when there are none"},"paidAmount":{"type":"integer","minimum":0,"examples":[2878],"description":"Collected so far via payments applied to this invoice. `0` until the first one"},"amountDue":{"type":"integer","minimum":0,"examples":[2878],"description":"What is still owed: `total` less `credited` and `paidAmount`, and `0` on one that is paid, void or credited in full"},"creditedAt":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},{"type":"null"}],"examples":[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"},"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 raised this invoice"},"voidedBy":{"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 voided this invoice. Null unless `status` is `void`"},"paidBy":{"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 recorded this invoice as paid. Null unless `status` is `paid` through that path"},"sharedBy":{"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 last shared this invoice. Null until it has ever been shared"}},"required":["id","number","customerId","currency","lines","subtotal","taxBps","tax","taxLines","reverseCharge","total","status","overdue","shared","issuedAt","dueAt","paidAt","voidedAt","note","credited","paidAmount","amountDue","creditedAt","issuer","actor","voidedBy","paidBy","sharedBy"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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_payable` or `no_credit`.","content":{"application/json":{"schema":{"description":"The request conflicts with the current state. `error` is `invoice_not_payable` or `no_credit`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"invoice_not_payable","message":"This invoice cannot take this payment","requestId":"req-4f"}},"example2":{"value":{"error":"no_credit","message":"This customer holds no credit in this currency","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/statement":{"get":{"operationId":"getCustomerStatement","summary":"Get a customer's statement","tags":["Payments"],"description":"Opening balance, every invoice, credit note, payment and refund in the date range, and the closing balance: one row set for each currency this customer has been billed, paid or refunded in. `GET /customers/{id}/statement.csv` with the same query returns the same rows as CSV.","parameters":[{"schema":{"type":"string","format":"date-time"},"example":"2026-10-07T11:04:31.000Z","in":"query","name":"from","required":true,"description":"The start of the statement, inclusive"},{"schema":{"type":"string","format":"date-time"},"example":"2026-10-07T11:04:31.000Z","in":"query","name":"to","required":true,"description":"The end of the statement, inclusive"},{"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"examples":["USD"],"description":"ISO 4217 currency code"},"opening":{"type":"integer","examples":[2878],"description":"The running balance of everything dated before `from`"},"rows":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"type":{"type":"string","enum":["invoice","credit_note","payment","refund"]},"id":{"type":"string"},"number":{"type":"string","examples":["INV-0001"]},"amount":{"type":"integer","examples":[2878],"description":"Under zero on a payment or a credit note: both bring down what is owed"},"balance":{"type":"integer","examples":[2878],"description":"The running balance once this row is applied"}},"required":["date","type","id","number","amount","balance"],"additionalProperties":false}},"closing":{"type":"integer","examples":[2878],"description":"`opening` plus every row above added together"}},"required":["currency","opening","rows","closing"],"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"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/statement.csv":{"get":{"operationId":"getCustomerStatementCsv","summary":"Get a customer's statement as CSV","tags":["Payments"],"description":"`GET /customers/{id}/statement`'s own rows, as `text/csv`.","parameters":[{"schema":{"type":"string","format":"date-time"},"example":"2026-10-07T11:04:31.000Z","in":"query","name":"from","required":true,"description":"The start of the statement, inclusive"},{"schema":{"type":"string","format":"date-time"},"example":"2026-10-07T11:04:31.000Z","in":"query","name":"to","required":true,"description":"The end of the statement, inclusive"},{"schema":{"type":"string"},"example":"cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"string","contentMediaType":"text/csv"}}}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Billing runs"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the row's currency. Under zero on a skipped credit row"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line, when the account has set tax rules. Empty on a row priced from the flat default tax rate or with no tax at all"},"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","taxLines","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Billing runs"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the row's currency. Under zero on a skipped credit row"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line, when the account has set tax rules. Empty on a row priced from the flat default tax rate or with no tax at all"},"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","taxLines","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Billing runs"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the row's currency. Under zero on a skipped credit row"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line, when the account has set tax rules. Empty on a row priced from the flat default tax rate or with no tax at all"},"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","taxLines","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":["Billing runs"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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"},"taxLines":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"rateBps":{"type":"integer","minimum":0,"maximum":10000,"examples":[2000],"description":"Tax as a share of the subtotal, in basis points: 2000 is 20%"},"amount":{"type":"integer","examples":[2878],"description":"Minor units of the row's currency. Under zero on a skipped credit row"}},"required":["name","rateBps","amount"],"additionalProperties":false},"description":"How `tax` is made up, line by line, when the account has set tax rules. Empty on a row priced from the flat default tax rate or with no tax at all"},"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","taxLines","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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"]},"examples":{"example1":{"value":{"error":"run_not_previewed","message":"Only a run still being previewed can be changed","requestId":"req-4f"}},"example2":{"value":{"error":"row_not_pending","message":"This row has already been billed or skipped","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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.expiring","domain.needs_attention","domain.expired","domain.updated","domain.host_created","domain.host_updated","domain.host_deleted","domain.auth_code_generated","domain.transferred_out","domain.transfer.completed","domain.transfer.failed","domain.restored","domain.restore_failed","domain.deleted","domain.suspended","domain.unsuspended","subreseller.suspended","subreseller.unsuspended","reseller.branded_nameservers_created","reseller.branded_nameservers_removed","licence.created","licence.updated","licence.renewed","licence.renewal_failed","licence.cancelled","mailbox_domain.created","mailbox_domain.active","mailbox_domain.failed","mailbox_domain.renewed","mailbox_domain.renewal_failed","mailbox_domain.dns_broken","mailbox_domain.deleted","mailbox.created","mailbox.setup_progress","mailbox.active","mailbox.failed","mailbox.updated","client_id.completed","client_id.failed","price_list.updated","sale.below_cost","invoice.created","invoice.paid","invoice.voided","credit_note.issued","wallet.topped_up","portal.order.placed","portal.order.blocked","subreseller.margin_clawback_short"]}]}}},"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"},"healthState":{"type":"string","enum":["healthy","unhealthy","paused"],"description":"'unhealthy' is every delivery failing for a day; 'paused' is seven, and stops new deliveries being attempted (they still queue, nothing is lost) until it is fixed"},"secret":{"type":"string","examples":["whsec_MfKQ9r8GKYqrTwjUPD8ILPZIo2LaLaSw"],"description":"The signing secret. Store it now; it is not shown again"}},"required":["id","url","events","enabled","createdAt","healthState","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"]},"examples":{"example1":{"value":{"error":"invalid_webhook_url","message":"Webhook URL must use https and resolve to a public address","requestId":"req-4f"}},"example2":{"value":{"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` or `step_up_required`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized` or `step_up_required`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}},"example2":{"value":{"error":"step_up_required","message":"Confirm it is you before doing this again.","requestId":"req-4f"}}}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"},"healthState":{"type":"string","enum":["healthy","unhealthy","paused"],"description":"'unhealthy' is every delivery failing for a day; 'paused' is seven, and stops new deliveries being attempted (they still queue, nothing is lost) until it is fixed"}},"required":["id","url","events","enabled","createdAt","healthState"],"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List an endpoint's recent deliveries","tags":["Webhooks"],"description":"Newest first: what was sent, when, and how it went. A `failed` or `blocked` one can be sent again with `POST /webhook-deliveries/{id}/redeliver`.","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":"whe_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":["whd_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"endpointId":{"type":"string","examples":["whe_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"eventId":{"type":"string","examples":["evt_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"status":{"type":"string","enum":["pending","blocked","succeeded","failed"],"description":"'blocked' is waiting behind an earlier, unresolved delivery about the same subject, so the two are never sent out of order"},"attempts":{"type":"integer","minimum":0},"lastStatusCode":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[200]},"lastError":{"type":["string","null"]},"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","endpointId","eventId","status","attempts","lastStatusCode","lastError","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"}}}},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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-deliveries/{id}/redeliver":{"post":{"operationId":"redeliverWebhookDelivery","summary":"Resend a delivery","tags":["Webhooks"],"description":"Queues a fresh delivery of the same event to the same endpoint, carrying the same event id so a receiver that de-dupes on it sees no difference from the original. Goes out right away, ahead of anything else queued for this endpoint and subject.","parameters":[{"schema":{"type":"string"},"example":"whd_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["whd_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"endpointId":{"type":"string","examples":["whe_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"eventId":{"type":"string","examples":["evt_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"status":{"type":"string","enum":["pending","blocked","succeeded","failed"],"description":"'blocked' is waiting behind an earlier, unresolved delivery about the same subject, so the two are never sent out of order"},"attempts":{"type":"integer","minimum":0},"lastStatusCode":{"anyOf":[{"type":"integer"},{"type":"null"}],"examples":[200]},"lastError":{"type":["string","null"]},"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","endpointId","eventId","status","attempts","lastStatusCode","lastError","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"},"level":{"type":"string","enum":["read","manage","buy"],"description":"What this key may do: 'read' reads only, 'manage' also changes what you already own, 'buy' also spends money. Absent means no ceiling at all, the same as every key made before this field existed"},"perOrderLimit":{"description":"Largest single order this key may place, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"dailyLimit":{"description":"Most this key may spend in one UTC day, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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"]},"level":{"type":"string","enum":["read","manage","buy"],"description":"What this key may do: 'read' reads only, 'manage' also changes what you already own, 'buy' also spends money. Absent means no ceiling at all, the same as every key made before this field existed"},"perOrderLimit":{"description":"Largest single order this key may place, in cents. Absent means no ceiling","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"dailyLimit":{"description":"Most this key may spend in one UTC day, in cents. Absent means no ceiling","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]}},"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"},"level":{"type":"string","enum":["read","manage","buy"],"description":"What this key may do: 'read' reads only, 'manage' also changes what you already own, 'buy' also spends money. Absent means no ceiling at all, the same as every key made before this field existed"},"perOrderLimit":{"description":"Largest single order this key may place, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"dailyLimit":{"description":"Most this key may spend in one UTC day, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"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` or `step_up_required`.","content":{"application/json":{"schema":{"description":"The API key is missing, wrong or revoked. `error` is `unauthorized` or `step_up_required`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"unauthorized","message":"Missing or invalid credentials","requestId":"req-4f"}},"example2":{"value":{"error":"step_up_required","message":"Confirm it is you before doing this again.","requestId":"req-4f"}}}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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}":{"patch":{"operationId":"updateApiKey","summary":"Change an API key","tags":["Keys"],"description":"Changes what this key may do, or its spending ceilings. Only the fields sent change; send `null` to clear a limit or to give the key back full, unlevelled access.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"level":{"anyOf":[{"type":"string","enum":["read","manage","buy"],"description":"What this key may do: 'read' reads only, 'manage' also changes what you already own, 'buy' also spends money. Absent means no ceiling at all, the same as every key made before this field existed"},{"type":"null"}]},"perOrderLimit":{"description":"Largest single order this key may place, in cents. `null` clears it","anyOf":[{"type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},{"type":"null"}]},"dailyLimit":{"description":"Most this key may spend in one UTC day, in cents. `null` clears it","anyOf":[{"type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},{"type":"null"}]}}}}}},"parameters":[{"schema":{"type":"string"},"example":"key_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","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"},"level":{"type":"string","enum":["read","manage","buy"],"description":"What this key may do: 'read' reads only, 'manage' also changes what you already own, 'buy' also spends money. Absent means no ceiling at all, the same as every key made before this field existed"},"perOrderLimit":{"description":"Largest single order this key may place, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"dailyLimit":{"description":"Most this key may spend in one UTC day, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"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}}}},"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/assistant-activity":{"get":{"operationId":"listAssistantActivity","summary":"List assistant activity","tags":["Keys"],"description":"What your API keys and any connected assistant have done, newest first - including a call a spending limit refused, so a key handed to an integration is something you can watch rather than something you have to trust.","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"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["cac_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"credentialId":{"type":"string","examples":["ak_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"credentialName":{"examples":["production"],"type":"string"},"via":{"type":"string","enum":["rest","mcp"]},"tool":{"type":"string","examples":["POST /v1/domains"]},"outcome":{"type":"string","enum":["ok","validation_error","invalid_idempotency_key","invalid_contact","invalid_webhook_url","invalid_stripe_signature","carrier_not_accepted","unauthorized","step_up_required","insufficient_funds","ordering_unavailable","reseller_suspended","parent_suspended","numbers_disabled","insufficient_key_permissions","spend_limit_exceeded","not_found","customer_exists","domain_taken","hostname_taken","domain_owned","domain_expired","domain_locked","domain_not_in_redemption","domain_not_deletable","domain_not_modifiable","registrar_refused","host_in_use","branded_nameservers_exists","branded_nameservers_in_use","dns_not_supported","dns_not_hosted","dns_hosted","dns_busy","dns_record_managed","not_cancellable","cancel_too_soon","rental_not_active","rental_busy","domain_busy","transfer_in_progress","transfer_not_pending","licence_busy","licence_charge_in_doubt","user_exists","idempotency_in_progress","idempotency_key_reused","no_offer","service_required","country_not_offered","product_not_available","renewal_unavailable","not_available","logo_too_large","logo_unsupported_type","picture_too_large","picture_unsupported_type","not_pending_validation","resend_validation_unsupported","home_country_required","home_region_required","not_eu","apex_hostname","unsupported_tld","registrant_required","unsupported_period","premium_domain","domain_not_registered","ending_not_sold","privacy_unavailable","dnssec_unavailable","too_many_dnssec_keys","invalid_dnssec_key","invalid_domain","invalid_nameserver","invalid_dns_record","dns_record_conflict","too_many_dns_records","invalid_forward_url","invalid_forward_address","host_not_under_domain","invalid_host_address","invalid_branded_nameserver_count","unknown_plan","plan_not_available","invalid_mailbox","seats_cannot_be_lowered","not_enough_seats","stripe_not_configured","too_many_keys","too_many_endpoints","nested_sub_resellers_unsupported","sub_reseller_feature_unavailable","sub_reseller_invitations_live_only","sub_reseller_funding_live_only","sub_reseller_withdrawal_live_only","too_many_price_lists","live_only","live_in_use","product_already_on","too_many_promotions","duplicate_coupon","coupon_used_up","default_price_list","duplicate_rule","too_many_rules","invalid_rate","invalid_currency","invalid_dates","promotion_below_cost","unknown_coupon","coupon_expired","coupon_not_applicable","nothing_to_invoice","mixed_currencies","sale_unavailable","invoice_not_open","invoice_not_voidable","invoice_not_creditable","credit_conflict","run_not_previewed","row_not_pending","invalid_paid_at","credit_too_large","credit_line_unknown","invalid_credit","discount_too_large","invalid_discount","invalid_payment","invalid_refund","insufficient_credit","invoice_not_payable","allocation_too_large","no_credit","mailbox_domain_exists","domain_unavailable","google_workspace_unavailable","mailbox_domain_connected","mailbox_domain_deleting","mailbox_domain_failed","mailbox_domain_busy","mailbox_domain_not_active","customer_required","domain_not_active","domain_mismatch","customer_mismatch","domain_dns_elsewhere","mailbox_limit","invalid_username","invalid_name","invalid_password","mailbox_exists","mailbox_purchase_refused","mailbox_not_active","mailbox_provider_refused","mailboxes_unavailable","record_protected","invalid_url","invalid_forwarding","invalid_client_id","invalid_scopes","no_admin_mailbox","dns_managed_by_mailboxes","nameservers_used_by_mailboxes","dnssec_not_available","forwarding_not_available","product_retired","rate_limited","renewal_failed","check_failed","registrar_check_failed","registrar_unavailable","catalogue_loading","auth_code_failed","resend_validation_failed","restore_failed","delete_failed","host_failed","dns_failed"],"examples":["ok"],"description":"`ok`, or the error code the call ended with"},"summary":{"type":"string","examples":["Registered example.com for cus_… at $12.00."]},"amount":{"examples":[1200],"description":"In minor units (cents)","type":"integer"},"reference":{"type":"string"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","credentialId","via","tool","outcome","summary","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/mcp-connections":{"get":{"operationId":"listMcpConnections","summary":"List MCP connections","tags":["MCP connections"],"description":"Every assistant you have connected through MCP, the level and spending limits you granted it, and when it was last used.","responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"clientId":{"type":"string","examples":["https://chat.example.com/.well-known/oauth-client"]},"clientName":{"examples":["Claude"],"description":"The connecting assistant's own self-reported name. Never verified","type":["string","null"]},"level":{"anyOf":[{"type":"string","enum":["read","manage","buy"],"description":"What this key may do: 'read' reads only, 'manage' also changes what you already own, 'buy' also spends money. Absent means no ceiling at all, the same as every key made before this field existed"},{"type":"null"}],"description":"What this connection may do. `null` for one made before #578, which recorded no level"},"perOrderLimit":{"description":"Largest single order this connection may place, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"dailyLimit":{"description":"Most this connection may spend in one UTC day, in cents","type":"integer","minimum":0,"maximum":100000000,"examples":[500000]},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]},"lastUsedAt":{"format":"date-time","examples":[null],"description":"The last tool call made with this connection. `null` if it has never been used","type":["string","null"]}},"required":["clientId","clientName","level","createdAt","lastUsedAt"],"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"deleteMcpConnection","summary":"Disconnect an assistant","tags":["MCP connections"],"description":"Ends the connection at once: every access and refresh token issued to it stops working immediately, not merely the next time it is checked. This cannot be undone.","parameters":[{"schema":{"type":"string"},"in":"query","name":"clientId","required":true}],"responses":{"204":{"description":"Disconnected"},"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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers/invitations":{"post":{"operationId":"createSubResellerInvitation","summary":"Invite a sub-reseller","tags":["Sub-resellers"],"description":"Mails a single-use link that lets the invitee sign up as a reseller of their own, priced from the given list (unset, your default list). One level deep: an account that is itself a sub-reseller cannot invite another.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254,"format":"email","examples":["owner@sub-reseller.example"]},"name":{"type":"string","minLength":1,"maxLength":200,"examples":["Sub Reseller Co"]},"priceListId":{"description":"Unset, your default list","type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]}},"required":["email","name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"description":"Created","type":"object","properties":{"id":{"type":"string","examples":["sri_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["owner@sub-reseller.example"]},"name":{"type":"string","examples":["Sub Reseller Co"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Unset, the parent default price list"},"expiresAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","email","name","priceListId","expiresAt","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","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 `nested_sub_resellers_unsupported` or `sub_reseller_invitations_live_only`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `nested_sub_resellers_unsupported` or `sub_reseller_invitations_live_only`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"nested_sub_resellers_unsupported","message":"A sub-reseller cannot invite one of its own; one level is the limit","requestId":"req-4f"}},"example2":{"value":{"error":"sub_reseller_invitations_live_only","message":"Switch to live to invite a sub-reseller; sandbox invitations are not supported","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"listSubResellerInvitations","summary":"List pending sub-reseller invitations","tags":["Sub-resellers"],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["sri_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"email":{"type":"string","examples":["owner@sub-reseller.example"]},"name":{"type":"string","examples":["Sub Reseller Co"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Unset, the parent default price list"},"expiresAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","email","name","priceListId","expiresAt","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `sub_reseller_invitations_live_only`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `sub_reseller_invitations_live_only`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"sub_reseller_invitations_live_only","message":"Switch to live to invite a sub-reseller; sandbox invitations are not supported","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers/invitations/{id}":{"delete":{"operationId":"deleteSubResellerInvitation","summary":"Withdraw an invitation","tags":["Sub-resellers"],"description":"The token stops working at once, whether or not it has already expired.","parameters":[{"schema":{"type":"string"},"example":"sri_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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found` or `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found` or `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"]},"examples":{"example1":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}},"example2":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}}}},"422":{"description":"The request is well formed but cannot be carried out. `error` is `sub_reseller_invitations_live_only`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `sub_reseller_invitations_live_only`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"example":{"error":"sub_reseller_invitations_live_only","message":"Switch to live to invite a sub-reseller; sandbox invitations are not supported","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers":{"get":{"operationId":"listSubResellers","summary":"List your sub-resellers","tags":["Sub-resellers"],"description":"Every reseller invited through you, newest first, with the price list it is charged from and its wallet balance. One level deep: a sub-reseller has none of its own.","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"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","examples":["rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Sub Reseller Co"]},"status":{"type":"string","enum":["active","suspended"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Unset, your default list prices this sub-reseller"},"wallet":{"type":"object","properties":{"available":{"type":"integer","examples":[8800],"description":"Spendable balance, in cents"},"held":{"type":"integer","examples":[0],"description":"Reserved for orders in progress"}},"required":["available","held"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","status","priceListId","wallet","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers/{id}":{"get":{"operationId":"getSubReseller","summary":"Get a sub-reseller","tags":["Sub-resellers"],"parameters":[{"schema":{"type":"string"},"example":"rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Sub Reseller Co"]},"status":{"type":"string","enum":["active","suspended"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Unset, your default list prices this sub-reseller"},"wallet":{"type":"object","properties":{"available":{"type":"integer","examples":[8800],"description":"Spendable balance, in cents"},"held":{"type":"integer","examples":[0],"description":"Reserved for orders in progress"}},"required":["available","held"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","status","priceListId","wallet","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found` or `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found` or `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"]},"examples":{"example1":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}},"example2":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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":"updateSubReseller","summary":"Price or suspend a sub-reseller","tags":["Sub-resellers"],"description":"Sets the price list a sub-reseller is charged from (`null` clears it, so your default list prices it instead), its status, or both. Suspending stops it buying or renewing anything, same as suspending yourself does for your own account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}]},"status":{"type":"string","enum":["active","suspended"]},"reason":{"type":"string","minLength":1,"maxLength":500}}}}}},"parameters":[{"schema":{"type":"string"},"example":"rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA","in":"path","name":"id","required":true}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"description":"Success","type":"object","properties":{"id":{"type":"string","examples":["rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Sub Reseller Co"]},"status":{"type":"string","enum":["active","suspended"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Unset, your default list prices this sub-reseller"},"wallet":{"type":"object","properties":{"available":{"type":"integer","examples":[8800],"description":"Spendable balance, in cents"},"held":{"type":"integer","examples":[0],"description":"Reserved for orders in progress"}},"required":["available","held"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","status","priceListId","wallet","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found` or `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found` or `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"]},"examples":{"example1":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}},"example2":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers/{id}/orders":{"get":{"operationId":"listSubResellerOrders","summary":"List a sub-reseller's number orders","tags":["Sub-resellers"],"description":"Orders with their numbers, newest first - the same shape your own `GET /numbers/orders` returns, minus `customerId` at both levels: a sub-reseller's own customers are not this account's to join.","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":"rsl_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":["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."},"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"]},"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]},"cancellableFrom":{"anyOf":[{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"},{"type":"null"}],"examples":[null],"description":"While the provider still holds a new number, the earliest it may be cancelled. Null when there is no wait left to name, or the number is no longer active"},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"],"description":"ISO 8601 timestamp"}},"required":["id","number","country","product","service","status","orderId","nickname","startsAt","endsAt","autoRenew","renewDuration","unitPrice","customerPrice","paidTotal","messageCount","cancellableFrom","createdAt"],"additionalProperties":false}},"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 placed this order"},"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","country","product","service","duration","quantity","fulfilledCount","autoRenew","unitPrice","totalPrice","currency","failure","numbers","actor","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found` or `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found` or `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"]},"examples":{"example1":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}},"example2":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers/{id}/sales":{"get":{"operationId":"listSubResellerSales","summary":"List a sub-reseller's sales","tags":["Sub-resellers"],"description":"Every purchase and renewal the sub-reseller made, newest first - the same shape as your own `GET /sales`, minus `customerId`: a sub-reseller's own customers are not this account's to join.","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":"rsl_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":["sal_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"product":{"type":"string","enum":["number","domain","domain_privacy","licence","mailbox"]},"action":{"type":"string","enum":["new","renew","restore","transfer"],"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","enum":["hold","domain","domain_transfer","domain_privacy","licence","mailbox","mailbox_domain","number_order","number_rental","reconciliation_case","stripe_checkout_session","stripe_refund","stripe_dispute"]},"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","enum":["USD","EUR","GBP","CAD","AUD","NZD","CHF","SEK","NOK","DKK","PLN","INR","SGD","HKD","AED","ZAR","BRL","MXN"],"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","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"}}}},"403":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found` or `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found` or `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"]},"examples":{"example1":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}},"example2":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}}}}}},"429":{"description":"Too many requests. Slow down and retry. `error` is `rate_limited`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers/{id}/fund":{"post":{"operationId":"fundSubReseller","summary":"Fund a sub-reseller","tags":["Sub-resellers"],"description":"Moves money out of your own wallet and into a sub-reseller's, in one step. Refused when either account is suspended, or when your own balance cannot cover it, with nothing moved either way. Send an Idempotency-Key header so a retry can never move the money twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"examples":[5000],"description":"In cents"},"memo":{"type":"string","minLength":1,"maxLength":200}},"required":["amount"]}}}},"parameters":[{"schema":{"type":"string"},"example":"rsl_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":["rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Sub Reseller Co"]},"status":{"type":"string","enum":["active","suspended"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Unset, your default list prices this sub-reseller"},"wallet":{"type":"object","properties":{"available":{"type":"integer","examples":[8800],"description":"Spendable balance, in cents"},"held":{"type":"integer","examples":[0],"description":"Reserved for orders in progress"}},"required":["available","held"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","status","priceListId","wallet","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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 `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `reseller_suspended` or `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"Written for a person; do not parse it"},"requestId":{"type":"string","description":"Quote this when asking for help"}},"required":["error","message","requestId"]},"examples":{"example1":{"value":{"error":"reseller_suspended","message":"This account is suspended","requestId":"req-4f"}},"example2":{"value":{"error":"insufficient_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found` or `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found` or `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"]},"examples":{"example1":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}},"example2":{"value":{"error":"not_found","message":"Number not found","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 `sub_reseller_funding_live_only` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `sub_reseller_funding_live_only` 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"]},"examples":{"example1":{"value":{"error":"sub_reseller_funding_live_only","message":"Switch to live to fund a sub-reseller; sandbox funding is not supported","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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/sub-resellers/{id}/withdraw":{"post":{"operationId":"withdrawFromSubReseller","summary":"Withdraw unspent funds from a sub-reseller","tags":["Sub-resellers"],"description":"Moves money out of a sub-reseller's wallet and back into your own, the mirror of fund. Moves only what is available: a sub-reseller's held funds belong to orders in flight and are never disturbed, so an over-withdrawal is refused with nothing moved. Allowed even when the sub-reseller is suspended, since suspension only stops it spending - the money withdrawn is yours to recover. Send an Idempotency-Key header so a retry can never move the money twice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"examples":[5000],"description":"In cents"},"memo":{"type":"string","minLength":1,"maxLength":200}},"required":["amount"]}}}},"parameters":[{"schema":{"type":"string"},"example":"rsl_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":["rsl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},"name":{"type":"string","examples":["Sub Reseller Co"]},"status":{"type":"string","enum":["active","suspended"]},"priceListId":{"anyOf":[{"type":"string","examples":["prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"]},{"type":"null"}],"description":"Unset, your default list prices this sub-reseller"},"wallet":{"type":"object","properties":{"available":{"type":"integer","examples":[8800],"description":"Spendable balance, in cents"},"held":{"type":"integer","examples":[0],"description":"Reserved for orders in progress"}},"required":["available","held"],"additionalProperties":false},"createdAt":{"type":"string","format":"date-time","examples":["2026-10-07T11:04:31.000Z"]}},"required":["id","name","status","priceListId","wallet","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"]},"examples":{"example1":{"value":{"error":"validation_error","message":"querystring/country must match pattern \"^[A-Z]{2}$\"","requestId":"req-4f"}},"example2":{"value":{"error":"invalid_idempotency_key","message":"Idempotency-Key must be 8 to 200 characters","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 `insufficient_key_permissions`.","content":{"application/json":{"schema":{"description":"The account is suspended, or missing a feature this needs. `error` is `insufficient_key_permissions`.","type":"object","properties":{"error":{"type":"string","description":"A stable code you can branch on"},"message":{"type":"string","description":"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_key_permissions","message":"This API key's level does not reach this route; it needs a 'buy' key.","requestId":"req-4f"}}}},"404":{"description":"No such resource on this side of the account. `error` is `not_found` or `not_found`.","content":{"application/json":{"schema":{"description":"No such resource on this side of the account. `error` is `not_found` or `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"]},"examples":{"example1":{"value":{"error":"not_found","message":"Number not found","requestId":"req-4f"}},"example2":{"value":{"error":"not_found","message":"Number not found","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 `sub_reseller_withdrawal_live_only` or `idempotency_key_reused`.","content":{"application/json":{"schema":{"description":"The request is well formed but cannot be carried out. `error` is `sub_reseller_withdrawal_live_only` 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"]},"examples":{"example1":{"value":{"error":"sub_reseller_withdrawal_live_only","message":"Switch to live to withdraw from a sub-reseller; sandbox withdrawal is not supported","requestId":"req-4f"}},"example2":{"value":{"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`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying"}},"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://app.resellerhq.com/api"},{"url":"https://api.resellerhq.com"}],"security":[{"apiKey":[]}],"tags":[{"name":"Account","description":"The account an API key belongs to."},{"name":"Wallet","description":"The prepaid balance and its history."},{"name":"Keys","description":"API keys for calling this API."},{"name":"Customers","description":"The people you sell to."},{"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":"Numbers","description":"Phone numbers that receive SMS."},{"name":"Domains","description":"Domain search, registration and renewal."},{"name":"DNS","description":"Hosted DNS for a domain: the zone and its records. Included, free."},{"name":"Mailboxes","description":"Google mailboxes, set up end to end, with their sign-in details."},{"name":"Sub-resellers","description":"Resellers you supply, fund and price."},{"name":"Webhooks","description":"Endpoints that receive signed events."},{"name":"MCP connections","description":"Assistants connected through MCP, and what you have let them do."},{"name":"Activity","description":"Who changed what in your account, and when."},{"name":"Customer portal","x-parent":"Account","description":"The portal your customers buy from: its look, its draft, and publishing it."},{"name":"Tax","x-parent":"Account","description":"The tax your invoices charge."},{"name":"Hostnames","x-parent":"Account","description":"Your own hostnames for the customer portal."},{"name":"Branded nameservers","x-parent":"Account","description":"Nameservers under your own domain, for the domains you sell."},{"name":"Domain transfers","x-displayName":"Transfers","x-parent":"Domains","description":"Domains moved in from another registrar."},{"name":"Child nameservers","x-parent":"Domains","description":"Hosts under a domain that serve as nameservers (glue records)."},{"name":"Price lists","x-parent":"Pricing","description":"What your customers pay, by list, and quoting from it."},{"name":"Contract prices","x-parent":"Pricing","description":"Prices fixed for one customer."},{"name":"Promotions","x-parent":"Pricing","description":"Discounts for a time, a product or a code."},{"name":"Sales","x-parent":"Pricing","description":"What you have sold, and what you made on it."},{"name":"Credit notes","x-parent":"Invoices","description":"Money taken off an invoice already issued."},{"name":"Payments","x-displayName":"Payments and statements","x-parent":"Invoices","description":"What customers paid, what was refunded, and what they owe."},{"name":"Billing runs","x-parent":"Invoices","description":"Invoicing every customer for a period in one go."},{"name":"Mailbox DNS","x-displayName":"DNS","x-parent":"Mailboxes","description":"A mailbox domain's records, and checking and repairing the ones mail needs."},{"name":"Mailbox domain settings","x-displayName":"Forwarding, DMARC and OAuth","x-parent":"Mailboxes","description":"A mailbox domain's website forwarding, DMARC policy and OAuth client IDs."},{"name":"Mailbox domains","x-displayName":"Domains","x-parent":"Mailboxes","description":"The domains mailboxes are on: connecting one ahead of an order, and deleting it."}],"x-tagGroups":[{"name":"Start here","tags":["Account","Wallet","Keys"]},{"name":"Customers and billing","tags":["Customers","Pricing","Invoices","Orders"]},{"name":"Products","tags":["Numbers","Domains","DNS","Mailboxes"]},{"name":"Reselling","tags":["Sub-resellers"]},{"name":"Integrations","tags":["Webhooks","MCP connections","Activity"]}]}