---
title: "Create hosted checkout link"
method: POST
path: "/checkout/create"
tags: ["Checkout"]
---

# Create hosted checkout link

`POST /checkout/create`

Creates a short-lived hosted checkout URL for a package, one domain, or up to 50 domain registrations. Use `package_id` with `cycle_id` for an existing package, `domain` with `years` for one domain, or `domains` for multiple domain registrations. `callback_url` is required. `customer_id` is optional; when supplied, it must reference a customer account (`account_type` 2). The checkout link is cached for 30 minutes. When the customer opens it, BillingServ creates a checkout-only session, allows supported saved payment methods, and redirects back to `callback_url` after payment. For package options, price, fee, and billing cycle are always resolved from the selected database option value; supplied `options.amount` and `options.cycle_type` values are accepted for request compatibility but do not override catalogue data.

## Request body

- union — Provide exactly one checkout type: an existing package, one domain, or a list of domains.
  - CheckoutPackageRequest — Creates hosted checkout for an existing package and billing cycle.
    - `package_id` integer, required — Package or order-group package ID to add to checkout.
    - `cycle_id` integer, required — Billing cycle ID for the selected package.
    - `callback_url` string, uri, required — URL BillingServ redirects to after hosted checkout succeeds or fails.
    - `customer_id` integer, nullable — Optional existing BillingServ customer user ID. If supplied, the user must have account_type 2.
    - `options` OrderOptionsRequest — Matching option arrays. Each index represents one selected package option. For hosted checkout, option prices are resolved server-side from the selected package.
      - `id` integer[], required
      - `amount` number[], required
      - `value` string[], required
      - `cycle_type` integer[], required
  - CheckoutDomainRequest — Creates hosted checkout for one available domain registration.
    - `domain` string, required — Full domain name to register, including its extension, such as `billingserv.co.uk`.
    - `years` integer, required — Registration period in years. The account domain setting may allow a lower maximum.
    - `callback_url` string, uri, required — URL BillingServ redirects to after hosted checkout succeeds or fails.
    - `customer_id` integer, nullable — Optional existing BillingServ customer user ID. If supplied, the user must have account_type 2.
  - CheckoutDomainsRequest — Creates one hosted checkout containing up to 50 available domain registrations.
    - `domains` DomainCheckoutItem[], required
      - `domain` string, required — Full domain name to register, including its extension.
      - `years` integer, required — Registration period in years. The account domain setting may allow a lower maximum.
    - `callback_url` string, uri, required — URL BillingServ redirects to after hosted checkout succeeds or fails.
    - `customer_id` integer, nullable — Optional existing BillingServ customer user ID. If supplied, the user must have account_type 2.

## Response `200`

OK

- HostedCheckoutResponse — A hosted checkout URL created by BillingServ. The URL expires after 30 minutes if it is not completed.
  - `success` true, required
  - `message` string, required
  - `url` string, uri, required — Hosted checkout URL to open or redirect the customer to.

## Other responses

- `401` — Missing or invalid API key
- `403` — Authenticated key does not have permission for this endpoint
- `422` — Validation or domain availability error
- `429` — Rate limit exceeded
- `502` — The domain registrar could not confirm availability

## Changes

- **2026-08-22** `6b9208b64456` — 11 info
  - added the new optional request property `oneOf[#/components/schemas/CheckoutPackageRequest]/options` (media type: application/json)
  - added the new optional request property `oneOf[#/components/schemas/CheckoutPackageRequest]/options` (media type: application/x-www-form-urlencoded)
  - added the non-success response with the status `429`
  - added the optional property `code` to the response with the `401` status
  - …7 more
- **2026-08-15** `f3171dce6f0f` — 1 breaking, 8 warning, 8 info
  - the request's body type/format changed from `object`/`` to ``/`` (media type: application/json)
  - removed the request property `callback_url` (media type: application/json)
  - removed the request property `callback_url` (media type: application/x-www-form-urlencoded)
  - removed the request property `customer_id` (media type: application/json)
  - …13 more

[Change history](https://skmtc.dev/b-cdn/apis/billingserv-api-v2/changes/checkout/create/post.md)

---

[API](https://skmtc.dev/b-cdn/apis/billingserv-api-v2.md) · [All operations](https://skmtc.dev/b-cdn/apis/billingserv-api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/b-cdn/billingserv-api-v2/revisions/76cfbed5eb40/schema)