> ## Documentation Index
> Fetch the complete documentation index at: https://www.billingserv.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Domain Search and Hosted Checkout API Guide

> Use the BillingServ domain availability API and hosted checkout API to search extensions, register one or more domains, and return customers to your site after payment.

Want to sell domain registrations from your own website? BillingServ can handle the registrar lookup and payment flow while you keep control of the customer experience.

This guide shows how to search for available domain extensions, create a hosted checkout link, support checkout-first customers, and send customers back to your site after payment.

## Before you start

Prepare:

* A BillingServ v2 API key
* Your BillingServ API base URL
* A callback URL on your website
* A configured domain registrar with the extensions you want to sell enabled
* An existing BillingServ customer ID if you want to skip customer details during checkout

Keep the API key on your server. These requests should not run in browser code where visitors could inspect the credential.

## Authentication

Send the API key as a bearer token with every request:

```http theme={null}
Authorization: Bearer <live_api_key>
Accept: application/json
Content-Type: application/json
```

The API uses the v2 base URL:

```text theme={null}
https://your-billingserv-domain.com/api/v2
```

## 1. Search for available domain extensions

Use [POST /domain/lookup](/docs/api-reference/endpoint/domain-lookup) to check a name across the domain extensions enabled in your BillingServ account. Send the name without an extension. For example, use `billingserv`, not `billingserv.com`.

The optional `limit` field controls how many extensions are checked. It accepts values from 1 to 50 and defaults to 50.

```bash theme={null}
curl -X POST "https://your-billingserv-domain.com/api/v2/domain/lookup" \
  -H "Authorization: Bearer <live_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "billingserv",
    "limit": 10
  }'
```

The response includes one result for each enabled extension checked:

```json theme={null}
{
  "success": true,
  "domain": "billingserv",
  "registrar": "openprovider",
  "results": [
    {
      "domain": "billingserv.co.uk",
      "extension": "co.uk",
      "available": true,
      "premium": false
    },
    {
      "domain": "billingserv.com",
      "extension": "com",
      "available": false,
      "premium": false
    }
  ]
}
```

Use results with `available: true` when you build the domain selection step. Keep the `premium` value visible if premium domains need a different price or review process in your store.

## 2. Create a hosted checkout link

After the customer chooses a domain, call [POST /checkout/create](/docs/api-reference/endpoint/checkout-create). BillingServ checks availability again before creating the checkout link. That second check helps prevent a customer from paying for a domain that became unavailable after the search.

The request supports three checkout types:

| Checkout type    | Required fields                                            |
| :--------------- | :--------------------------------------------------------- |
| Existing package | `package_id`, `cycle_id`                                   |
| One domain       | `domain`, `years`                                          |
| Multiple domains | `domains`, with a `domain` and `years` value for each item |

Every checkout request also needs `callback_url`. `customer_id` is optional. When you provide it, it must belong to a BillingServ customer account.

Here is a one-domain checkout request:

```bash theme={null}
curl -X POST "https://your-billingserv-domain.com/api/v2/checkout/create" \
  -H "Authorization: Bearer <live_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "billingserv.co.uk",
    "years": 1,
    "customer_id": 123,
    "callback_url": "https://store.example.com/domain-complete"
  }'
```

BillingServ returns a hosted checkout URL:

```json theme={null}
{
  "success": true,
  "message": "Successfully",
  "url": "https://your-billingserv-domain.com/checkout/00000000-0000-0000-0000-000000000000"
}
```

Redirect the customer to `url`. The link is cached for 30 minutes and is invalidated after a completed payment. If the domain is unavailable, the API returns a `422` response and does not create a checkout link. If the registrar cannot confirm availability, the API returns `502`.

## 3. Support checkout-first customers

You do not need a customer ID to create a domain checkout. Leave `customer_id` out when you want BillingServ to collect the customer's details during the hosted checkout flow.

If you provide `customer_id`, use the ID of an existing customer account. Client and staff account IDs are not valid for this endpoint.

## 4. Check out multiple domains in one flow

Send a `domains` array when the customer wants more than one registration. Each item needs a full domain name and a registration period in years.

```bash theme={null}
curl -X POST "https://your-billingserv-domain.com/api/v2/checkout/create" \
  -H "Authorization: Bearer <live_api_key>" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "domains": [
      {
        "domain": "billingserv.co.uk",
        "years": 1
      },
      {
        "domain": "billingserv.com",
        "years": 1
      }
    ],
    "customer_id": 123,
    "callback_url": "https://store.example.com/domains-complete"
  }'
```

You can include up to 50 domains in one request. BillingServ checks every domain before returning the checkout link. Do not combine `domains` with `domain`, `package_id`, or `cycle_id` in the same request.

## 5. Keep package checkout working

The same endpoint still supports checkout for an existing package. Send `package_id` and `cycle_id` instead of domain fields:

```json theme={null}
{
  "package_id": 100,
  "cycle_id": 105,
  "customer_id": 123,
  "callback_url": "https://store.example.com/package-complete"
}
```

Use exactly one checkout type per request. This keeps package orders and domain registrations separate in the checkout flow.

## 6. Handle the payment callback

After the hosted checkout finishes, BillingServ redirects the customer to your `callback_url`.

A successful payment includes:

```text theme={null}
?transaction_id=<gateway_transaction_id>&internal_transaction_id=<billingserv_transaction_id>&status=success&order_ref=<payment_session_code>&external_customer_id=<customer_id>
```

A failed payment includes:

```text theme={null}
?status=failed&external_customer_id=<customer_id>
```

`external_customer_id` is included when you supplied `customer_id` in the checkout request. Treat the callback as a browser return, not as your only payment confirmation. For server-side reconciliation, use the transaction and order identifiers with the BillingServ API and configure [webhooks](/docs/api-reference/webhooks/overview) for payment events.

## Error handling

| Status | What it means                                                                                                  |
| :----- | :------------------------------------------------------------------------------------------------------------- |
| `401`  | The API key is missing or invalid.                                                                             |
| `403`  | The authenticated key cannot use the endpoint.                                                                 |
| `422`  | The request is invalid or a requested domain is unavailable.                                                   |
| `429`  | The domain availability rate limit was exceeded. The lookup endpoint allows 30 requests per minute per client. |
| `502`  | The registrar could not confirm domain availability during checkout.                                           |

For a `422` response, show the returned error and ask the customer to choose another domain or correct the request. For a `502` response, retry from your server with a short backoff and keep the customer selection available.

## Next steps

Read the [API overview](/docs/api-reference/introduction) for authentication and response conventions. When you are ready to reconcile completed payments, use the [webhook overview](/docs/api-reference/webhooks/overview) alongside the domain availability and hosted checkout API.