---
name: register-checkout-domain
description: Register the domain a seller's checkout is served from so Paddle opens live checkout on it — host the Apple Pay association file, `POST /checkout-domains`, poll to `approved` (resubmit if rejected), verify Apple Pay, and set the live default payment link.
metadata:
  internal: true
---

# Register checkout domains

## When to use this skill

Use this skill during go-live: Paddle only opens checkout on domains that are registered and approved. Register the domain the seller's checkout is served from, verify Apple Pay for it, and set it as the seller's live default payment link. You can register multiple domains, so sellers can publish to custom domains as well as your platform.

Domain registration uses your **partner API key** (`psk_...` + `Paddle-PartnerID`). This runs on **live** only. Make sure the seller's app is published and [prepared for go-live](/partners/embed-billing/seller-go-live/prepare-for-go-live) first — Paddle fetches the live site during review.

## 1. Host the Apple Pay domain-association file

Do this first: Paddle attempts Apple Pay verification at the same time as domain review, so you can clear both together. Host [Paddle's Apple Pay domain-association file](https://developer.paddle.com/assets/files/apple-developer-merchantid-domain-association) at:

```text
.well-known/apple-developer-merchantid-domain-association
```

It must be served directly over HTTPS, return `200`, and not redirect. If you skip this, sellers can still offer Apple Pay — Paddle opens a modal that then opens Apple Pay, with an extra step.

## 2. Register the checkout domain

```bash
curl -X POST https://api.paddle.com/checkout-domains \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Paddle-PartnerID: $PARTNER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "checkout.aeroedit.com" }'
```

A `201` returns the checkout domain (prefixed `chedom_`). It starts in `pending_review` while Paddle reviews it asynchronously, then moves to `approved`.

```json
{
  "data": {
    "id": "chedom_01j8z3k9m2n4p5q6r7s8t9v0w1",
    "domain": "checkout.aeroedit.com",
    "status": "pending_review",
    "payment_method_verification": { "apple_pay": { "status": "unverified" } }
  },
  "meta": { "request_id": "10c8f1a2-3b4c-4d5e-9f70-8a9b0c1d2e3f" }
}
```

## 3. Poll for approval, and resubmit if rejected

Review is automated and usually takes a few minutes. Poll `GET /checkout-domains/{checkout_domain_id}` until `status` is `approved`.

```bash
curl https://api.paddle.com/checkout-domains/chedom_01j8z3k9m2n4p5q6r7s8t9v0w1 \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Paddle-PartnerID: $PARTNER_ID"
```

If `status` is `action_required`, the domain didn't pass — but it's fixable. Check that pages are publicly accessible (not behind a login), pricing is visible, and terms, privacy notice, and refund policy exist with terms naming Paddle as merchant of record. Use your agent to fix these (see [`draft-seller-policies`](/partners/embed-billing/seller-go-live/minimum-seller-terms)), then resubmit — the endpoint takes **no body** and returns the domain to `pending_review`:

```bash
curl -X POST https://api.paddle.com/checkout-domains/chedom_01j8z3k9m2n4p5q6r7s8t9v0w1/resubmit \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Paddle-PartnerID: $PARTNER_ID"
```

## 4. Verify Apple Pay

Once the domain is `approved` **and** the association file is hosted, start Apple Pay verification. (You can't do this before the domain is approved.)

```bash
curl -X POST https://api.paddle.com/checkout-domains/chedom_01j8z3k9m2n4p5q6r7s8t9v0w1/verify-payment-method \
  -H "Authorization: Bearer $PARTNER_API_KEY" \
  -H "Paddle-PartnerID: $PARTNER_ID" \
  -H "Content-Type: application/json" \
  -d '{ "payment_method": "apple_pay" }'
```

A `200` returns the domain. When `payment_method_verification.apple_pay.status` is `verified`, Apple Pay is served directly from the seller's domain without the extra modal.

## 5. Set the live default payment link

A default payment link is required for Paddle to open a checkout, and it must point at a registered, approved domain. Set it once the domain is `approved` — `PATCH /settings/account` with a `default_checkout_url` on that domain (using the seller's `api_key`; see [`configure-seller-account`](/partners/embed-billing/onboard-sellers/configure-account)).

```bash
curl -X PATCH https://api.paddle.com/settings/account \
  -H "Authorization: Bearer $SELLER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "default_checkout_url": "https://checkout.aeroedit.com" }'
```

## Common pitfalls

- **Registering before the app is published.** Paddle fetches the live site during review; an unpublished or login-walled site fails. Prepare for go-live first.
- **Verifying Apple Pay too early.** The domain must be `approved` before `/verify-payment-method` succeeds.
- **Forgetting the live default payment link.** Without it, live checkout fails with "Something went wrong," even with an approved domain.
- **Login walls / missing pricing / no MoR mention in terms.** The most common `action_required` causes — fix, then resubmit.

## Verify

- `POST /checkout-domains` returns `201` with `status: "pending_review"`.
- `GET /checkout-domains/{id}` reaches `status: "approved"`.
- After `/verify-payment-method`, `payment_method_verification.apple_pay.status` is `verified`.
- With the live default payment link set on the approved domain, a live checkout opens.

## Related docs

- [Register checkout domains](/partners/embed-billing/seller-go-live/checkout-domains)
- [Prepare a seller for go-live](/partners/embed-billing/seller-go-live/prepare-for-go-live)
- [`configure-seller-account`](/partners/embed-billing/onboard-sellers/configure-account), [`draft-seller-policies`](/partners/embed-billing/seller-go-live/minimum-seller-terms)