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

---

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