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

# Create hosted checkout link

`POST /checkout/create`

## Request

- Base URL: `https://demo.onlinebillingform.com/api/v2`
- URL: `https://demo.onlinebillingform.com/api/v2/checkout/create`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/billingserv/apis/billingserv-api-v2/docs/checkout/create/post.ts> (a function with typed inputs; its response is checked against the schema)

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 changed from `object` to no type (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

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

---

[API](https://skmtc.dev/billingserv/apis/billingserv-api-v2.md) - [All operations](https://skmtc.dev/billingserv/apis/billingserv-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/billingserv/apis/billingserv-api-v2/revisions/232ab5ca8413?raw)