Bestellingen

Accountscope vereist; voeg de header X-Auth-Account toe met je Account-ID. Index/show vereisen de OAuth-scope billing:read; create / update / destroy zijn niet beschikbaar via OAuth (er is bewust geen billing:write-scope) — die vereisen een sessie- of API-sleutel-credential.

Bestellen verloopt via het cart-/facturatiesysteem en belast de standaard opgeslagen betaalmethode van het account off-session. Er is geen Stripe checkout-redirect.

Twee soorten bestellingen

POST /api/orders voorziet WordPress-sites. POST /api/orders/domain registreert of verhuist een domein via dezelfde cart-/facturatiestroom. Beide geven altijd een 202 cart-envelop terug en zijn OAuth-geblokkeerd (vereisen een sessie- of API-sleutel-credential).

Alle bestellingen van een account opvragen

GET /api/orders

Params (optioneel)

page: Integer | paginanummer (standaard: 1)
per_page: Integer | records per pagina (standaard: 50, max: 100)

Teruggegeven params

orders: Array
- id: String | uuid
- status: String
- created_at: DateTime
- updated_at: DateTime
- location: String | location short_name, of null voor bestellingen zonder locatie (bijv. domeinregistratiebestellingen)
- account: Object
  - id: String
  - name: String

Een bestelling bekijken

GET /api/orders/:id

Poll dit endpoint totdat status een eindwaarde bereikt (completed, failed, cancelled).

Teruggegeven params

order: Object
- id: String | uuid
- status: String
- created_at: DateTime
- updated_at: DateTime
- location: String | location short_name, of null voor bestellingen zonder locatie (bijv. domeinregistratiebestellingen)
tasks: Array
- id: Integer
- status: String
site: Object | aanwezig wanneer de bestelling een site heeft voorzien
- id: String
- name: String
- domain: String
- variant: String
- location: String
- ssh_data: Object | null wanneer de site geen SFTP-gegevens heeft
  - ipaddr: String
  - username: String
  - password: String
  - port: Integer
subscription: Object | aanwezig wanneer de bestelling een onderliggend abonnement heeft
- id: Integer | het interne numerieke ID van het abonnement — zie de waarschuwing hieronder
- status: String
- bucket_type: String
- bucket_year: Integer
- bucket_month: Integer
- stripe_id: String
domain: Object | aanwezig wanneer de bestelling een domein heeft geregistreerd of verhuisd
- name: String
- action: String | register of transfer
- registration: Object | het domeinregistratierecord — zie Domeinregistratie. null tijdens het asynchrone venster, totdat de registrar-aanroep slaagt
- provisioning_status: String | alleen aanwezig zolang registration null is; spiegelt de status van de bestelling
payment: Object
- status: String | pending, processing, succeeded, awaiting_authentication of failed — zie de opmerking hieronder
- method_type: String | het bepaalde Stripe-betaalmethodetype, of null. Meestal card of sepa_debit, maar dit is een open verzameling — alleen al de uitgestelde bankincasso's omvatten us_bank_account, acss_debit, bacs_debit, au_becs_debit en customer_balance, en andere zoals ideal zijn mogelijk. Behandel elke onbekende waarde als geldig
- hosted_invoice_url: String | null
- amount_charged_cents: Integer | null totdat de Stripe-factuur is gespiegeld
- credit_applied_cents: Integer | null totdat de Stripe-factuur is gespiegeld
account: Object | Zie accounts#show
user: Object | Zie users#show

subscription.id is niet het ID dat /api/subscriptions/:id accepteert

De subscription.id die hier wordt teruggegeven is het interne numerieke ID van het abonnement, terwijl GET /api/subscriptions/:id het abonnement opzoekt op guid — dezelfde waarde die Abonnementen opvragen als id teruggeeft. Dit ID rechtstreeks doorgeven aan het subscriptions-endpoint geeft 404 terug, zonder verdere uitleg. Zoek het abonnement op een ander veld, of vraag de abonnementen van het account op en haal het daaruit.

payment.status heeft hier vijf waarden, niet drie

Bij het bekijken van een bestelling wordt payment.status afgeleid van de status van de bestelling zelf: pending (er is nog niets naar de payment intent geschreven), processing (belasting onderweg), succeeded (volledig betaald), awaiting_authentication (3DS/SCA-uitdaging geparkeerd voor herstel — verwijs de gebruiker naar hosted_invoice_url) of failed (geweigerd, teruggeboekt of geannuleerd). De 202 cart-envelop van POST /api/orders gebruikt een andere enum met drie waarden voor dezelfde sleutel — hergebruik niet één parser voor beide.

Een nieuwe site bestellen

POST /api/orders

Belast de standaard betaalmethode van het facturatieaccount off-session en voorziet asynchroon een WordPress-site. Er is geen synchrone succestak — het endpoint geeft altijd 202 Accepted terug met een polling-envelop.

Locatie- en plannamen vind je door het /api/about-endpoint te bevragen.

Pre-flight-controle

Vereist dat het facturatieaccount klaar is om te belasten — een Stripe-customer-ID, een opgeslagen standaard betaalmethode, en een volledig facturatiecontact. Als de controle faalt, wordt 400 met code: "no_default_payment_method" teruggegeven en wordt er geen bestelling aangemaakt. Accounts op een facturatieplan dat niet via Stripe afrekent, worden extern gefactureerd en slaan deze controle volledig over; zij geven dus nooit no_default_payment_method terug.

Params

site: Object (required)
- name: String | wordt geaccepteerd maar niet gebruikt — zie de opmerking hieronder
- variant: String (required) | vanilla, extendify
- location: String (required) | Location short_name (bijv. "pdx")
- plan: String (required) | Product short_name (bijv. "basic")
- term: String (required) | monthly of annual
callback: Object | optionele uitgaande melding die wordt ge-POST wanneer de asynchrone task van de bestelling klaar is — zie Callbacks
- authorization: String | volledige waarde van de Authorization-header. Voorbeeld: Bearer 12345
- url: String | volledig gekwalificeerde URL

Je kunt de site geen naam geven

site.name wordt door het endpoint geaccepteerd en vervolgens genegeerd. De site wordt vernoemd naar een domein dat in hetzelfde verzoek is besteld; wordt er geen domein besteld, dan krijgt de site een gegenereerd label op basis van de machinenaam van het account. Lees de echte naam van de site terug uit de bestelling zodra die is voorzien.

Teruggegeven params (altijd 202 Accepted)

status: String | "accepted"
cart: Object
- token: String
- status: String | active, processing, checked_out
- rollup_status: String | pending, processing, completed, ...
- poll_url: String | absolute URL, bijv. https://your-instance/api/carts/<token>
payment: Object
- status: String | processing, succeeded, awaiting_authentication
- method_type: String | het bepaalde Stripe-betaalmethodetype, of null. Meestal card of sepa_debit, maar dit is een open verzameling — alleen al de uitgestelde bankincasso's omvatten us_bank_account, acss_debit, bacs_debit, au_becs_debit en customer_balance, en andere zoals ideal zijn mogelijk. Behandel elke onbekende waarde als geldig
- hosted_invoice_url: String | null
orders: Array
- id: String | uuid
- status: String | pending
- poll_url: String | absolute URL, bijv. https://your-instance/api/orders/<id>

Poll cart.poll_url (of de poll_url van elke bestelling) totdat de bestellingen materialiseren en een eindtoestand bereiken. orders is leeg tijdens het asynchrone venster — het bestellings-ID ontdek je door de cart te pollen.

Payment status-enum (cart-envelop)

In deze envelop heeft payment.status precies drie waarden: processing (PI onderweg / off-session-belasting), succeeded (afgerond), of awaiting_authentication (3DS/SCA vereist of een herstelbare weigering — verwijs de gebruiker naar hosted_invoice_url). Bij SEPA bevestigt de methode als processing en wordt afgewikkeld in 1–5 werkdagen. GET /api/orders/:id gebruikt voor dezelfde sleutel een bredere enum met vijf waarden.

Op een facturatieplan dat niet via Stripe afrekent, blijft payment.status in de envelop op processing staan en bereikt het nooit succeeded — het eindsignaal voor die accounts is orders[].status die completed bereikt.

Fouten

Elke 4xx draagt naast errors een machineleesbare code. Er wordt niets belast en er wordt geen bestelling aangemaakt.

400 missing_account | de header X-Auth-Account ontbreekt
400 account_cannot_order | het account mag geen bestellingen aanmaken
400 unknown_variant | variant is geen bekend varianttype
400 unknown_location | location is geen bekende publieke locatie
400 over_capacity | de variant heeft geen voorraad op die locatie — opnieuw te proberen
400 unknown_term | term is niet monthly of annual
400 unknown_product | plan is niet bestelbaar op het facturatieplan van het account
400 no_price_for_plan | geen prijs voor plan bij de gevraagde term
400 item_add_failed | de cart weigerde het site-item
400 no_default_payment_method | facturatieaccount niet klaar om te belasten
422 cart_pay_failed | de off-session-belasting kon niet worden gestart

Betaling kon niet worden gestart (422)

Als de cart geldig is maar Cart::PayService de off-session-belasting niet kan starten, is de reactie 422 met code: "cart_pay_failed". (Een pre-flight-fout is 400; een fout bij het starten van de betaling is 422.)

Een domein registreren of verhuizen

POST /api/orders/domain

Registreert of verhuist een domein via dezelfde cart-/facturatiestroom als POST /api/orders, belast de standaard opgeslagen betaalmethode van het account off-session, en registreert (of verhuist) vervolgens asynchroon het domein en maakt een verlengingsabonnement en DNS-zone aan. Geeft altijd 202 Accepted terug met de gedeelde cart-envelop; poll /api/orders/:id (dat een domain-blok bevat) totdat status een eindwaarde heeft.

Niet beschikbaar via OAuth en vereist een user-scoped credential. Een system Account-bearer API key (geen gebruiker) geeft 401 user_required terug. Vereist de header X-Auth-Account én de feature flag domain-registration — wanneer de flag uit staat, wordt 503 feature_disabled teruggegeven. Trial-accounts geven 403 trial_account terug.

Params

domain: Object (required)
- name: String (required) | volledig gekwalificeerd, bijv. example.com
- action: String (optional) | register (standaard) of transfer
- authcode: String | vereist voor verhuizingen wanneer de TLD een authcode vereist
- contact: Object | inline registrant; vereist tenzij contact_source is opgegeven
  - first_name: String (required)
  - last_name: String (required)
  - organization: String (optional)
  - street_address: String (required)
  - post_code: String (required)
  - city: String (required)
  - state: String (optional/required per TLD)
  - country: String (required) | tweeletterige ISO-code
  - email: String (required)
  - phone: String (required) | E.164, bijv. +1.5555555555
  - extra_properties: Object | TLD-specifieke registryvelden (bijv. .it entityType)
- contact_source: Object | hergebruik de contacten van een eigen registratie in plaats van contact
  - registration_id: Integer (required) | een eigen DomainRegistration met een owner-contact
- role_contacts: Object (optional) | admin / billing / tech; elk:
  - source: String | same_as_owner (standaard), existing, of new
  - source_registration_id: Integer | wanneer source existing is
  - first_name, last_name, ... | dezelfde contactvelden als hierboven, wanneer source new is
callback: Object (optional) | hetzelfde callback-contract als POST /api/orders — zie Callbacks
- authorization: String | volledige waarde van de Authorization-header. Voorbeeld: Bearer 12345
- url: String | volledig gekwalificeerde URL

Geef een registrant op via óf een inline contact-object óf contact_source.registration_id (om de contacten van een eigen registratie te hergebruiken), niet beide.

Teruggegeven params (altijd 202 Accepted)

Identieke envelop als POST /api/orders:

status: String | "accepted"
cart: Object | { token, status, rollup_status, poll_url }
payment: Object | { status, method_type, hosted_invoice_url }
orders: Array | [{ id, status, poll_url }] (leeg tijdens het asynchrone venster)

Fouten

Autorisatie / gating:

401 user_required | system Account-bearer key (geen gebruiker)
503 feature_disabled | domeinregistratie niet ingeschakeld
403 trial_account | trial-accounts kunnen geen domeinen bestellen

Validatie (400, geen belasting / geen bestelling aangemaakt):

missing_account | de header X-Auth-Account ontbreekt
account_cannot_order | het account mag geen bestellingen aanmaken
invalid_action | action niet register of transfer
invalid_domain | naam faalde bij normalisatie/validatie
unsupported_tld | geen geconfigureerde TLD voor de naam
pricing_unavailable | geen bestelbare prijs voor het facturatieplan van het account
authcode_required | verhuizing van een TLD die een authcode vereist, maar geen opgegeven
incomplete_contact | inline contact mist verplichte velden
invalid_contact | inline contact heeft een onjuiste waarde (bijv. country niet 2 letters)
invalid_contact_source | contact_source.registration_id niet gevonden of zonder owner-contact
no_default_payment_method | facturatieaccount niet klaar om te belasten

Verwerking (422):

domain_unavailable | registry zegt dat de naam niet registreerbaar is (alleen register)
domain_availability_unknown | de beschikbaarheidscontrole zelf is mislukt, dus we kunnen niet zeggen of de naam registreerbaar is — probeer het opnieuw (alleen register)
domain_add_failed | cart weigerde het domein (bijv. al in eigendom)
domain_contact_invalid | registrant-contact geweigerd (body bevat violations)
domain_contact_needs_augmentation | TLD heeft extra contactvelden nodig (body bevat needs_augmentation)
cart_pay_failed | betaling kon niet worden gestart (eventuele voor dit verzoek aangemaakte contacten worden afgebroken)

domain_unavailable is niet hetzelfde als domain_availability_unknown

Alleen domain_unavailable zegt iets over de naam zelf — de registry gaf aan dat die niet geregistreerd kan worden. domain_availability_unknown betekent dat de beschikbaarheidscontrole zelf is mislukt, dus over de naam is niets bekend: probeer het opnieuw in plaats van de klant te vertellen dat de naam bezet is of alternatieven aan te bieden.

Een bestelling annuleren

Annuleert een lopende bestelling.

DELETE /api/orders/:id

Geeft 202 terug.

PATCH is een no-op

PATCH /api/orders/:id is gereserveerd en geeft 400 terug.

Carts

Poll de cart-status tijdens het asynchrone venster na POST /api/orders, een planwijziging van een site, of elk ander betaald endpoint dat met dezelfde cart-envelop antwoordt.

Accountscope vereist (X-Auth-Account). Scope: billing:read. Carts zijn gescoped naar je eigen account; een onbekend token geeft 404 terug.

GET /api/carts/:token

Het cart-token komt uit de create-response (cart.token / cart.poll_url). De responsstructuur weerspiegelt POST /api/orders, zodat je dezelfde parser kunt hergebruiken:

Teruggegeven params

status: String | "accepted"
cart: Object
- token: String
- status: String
- rollup_status: String
- poll_url: String
payment: Object
- status: String
- method_type: String | het bepaalde Stripe-betaalmethodetype, of null. Meestal card of sepa_debit, maar dit is een open verzameling — alleen al de uitgestelde bankincasso's omvatten us_bank_account, acss_debit, bacs_debit, au_becs_debit en customer_balance, en andere zoals ideal zijn mogelijk. Behandel elke onbekende waarde als geldig
- hosted_invoice_url: String | null
orders: Array
- id: String | uuid
- status: String
- poll_url: String