partner
POST /v1/partner/customers/{externalId}/domain-orders
Place a domain order for one of your customers, unpaid.
Authentication
Send an API key as a bearer token. The key must carry the partner.domains permission; a key without it is refused with 403, not 404.
This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.
Try it
Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.
curl -X POST https://api.zinndigital.com/v1/partner/customers/{externalId}/domain-orders \
-H "Authorization: Bearer zdk_live_…" \
-H "Content-Type: application/json" \
-d '{ "return_url": <string>, "cancel_url": <string>, "items": <PartnerDomainItem[]>, "currency": <string> }'Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console
Details
Prices every line from our catalogue, re-verifies every availability token and places the order pending_payment. ⛔ Nothing is charged here and no payment method is touched: the customer pays on the hosted page named by pay_url, and their browser is sent back to return_url (or cancel_url) with only ?order=<human_ref>&status=paid (or cancelled) appended. Both URLs must be https on a host allowlisted for your programme, matched exactly — anything else is a 422 and no order is placed. pay_url carries a secret that is stored nowhere and shown only in this response; it lives 24 hours. Idempotency-Key is required — a retry returns the same order with a fresh pay_url rather than buying the name twice. Requires partner.domains.
Parameters
| Name | Type | Required | What it is |
|---|---|---|---|
externalId (path) | string | Yes | YOUR id for that customer — whatever your own system calls them. It is what makes linking idempotent, and it is scoped to your partner programme: another partner's id is a 404… |
Idempotency-Key (header) | string | No | Client-generated key that makes an unsafe request replay-safe: the server stores the first response and returns it verbatim for repeats. |
Request body
| Name | Type | Required | What it is |
|---|---|---|---|
return_url | string | Yes | Where the customer's browser goes once the order is paid. https, on a host allowlisted for your programme (exact match, default port, no userinfo). |
cancel_url | string | Yes | Where the browser goes if the customer leaves without paying. Same rules. |
locale | string | No | The language the payment page opens in. |
items | PartnerDomainItem[] | Yes | — |
currency | string | Yes | — |
billing_country | string | No | Overrides the country on the customer's billing profile for this order. |
Response
| Name | Type | Required | What it is |
|---|---|---|---|
order_id | string | Yes | — |
human_ref | string | Yes | The reference the payment page returns to you as ?order=. |
pay_url | string | No | Only in the response that placed (or replayed) the order: the hosted page the customer pays on. It carries a secret that is stored nowhere — treat it as one. |
pay_expires_at | string | No | — |
org_id | string | Yes | — |
status | string | Yes | pending_payment for a freshly placed order; afterwards the order's lifecycle (paid, fulfilling, completed, partially_fulfilled, canceled, …). |
currency | string | Yes | — |
subtotal_minor | integer | Yes | — |
tax_minor | integer | Yes | — |
total_minor | integer | Yes | — |
lines | PartnerOrderLine[] | Yes | — |
Errors this endpoint can return
401 · 403 · 404 · 409 · 422 · 429