Ga naar inhoud

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
      • ipaddr: String
      • username: String
      • password: String
      • port: Integer
  • subscription: Object | aanwezig wanneer de bestelling een onderliggend abonnement heeft
    • id: String
    • status: String
    • bucket_type: String
    • bucket_year: Integer
    • bucket_month: Integer
    • stripe_id: String
  • payment: Object
    • status: String | zie de payment status-enum hieronder
    • method_type: String | card, sepa_debit, of null
    • hosted_invoice_url: String | null
    • amount_charged_cents: Integer
    • credit_applied_cents: Integer
  • account: Object | Zie accounts#show
  • user: Object | Zie users#show

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.

Params
  • site: Object (required)
    • name: String (required)
    • 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
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 | /api/carts/<token>
  • payment: Object
    • status: String | processing, succeeded, awaiting_authentication
    • method_type: String | card, sepa_debit, of null
    • hosted_invoice_url: String | null
  • orders: Array
    • id: String | uuid
    • status: String | pending
    • poll_url: String | /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

payment.status kan processing zijn (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.

Pre-flight-/validatiefouten (400)
  • no_default_payment_method | facturatieaccount niet klaar om te belasten
  • onbekende variant / location / term / plan
  • variant niet beschikbaar (boven capaciteit)
  • ontbrekende prijsinformatie
  • "Account unable to create orders."

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):

  • 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_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)

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 of een planwijziging van een site.

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 | card, sepa_debit, of null
    • hosted_invoice_url: String | null
  • orders: Array
    • id: String | uuid
    • status: String
    • poll_url: String