Skip to main content
When a domain’s deliverability is deteriorating, a swap replaces it with a fresh one inside the existing order - keeping the workspace, the customer, and the rest of the order intact. Two flavors:
  • Standard. Old domain retired immediately. Lower cost, fastest cutover, brief send-pause on that one domain.
  • Premium. Old domain stays warm 14 days alongside the new one. No sending interruption; smoother handoff during warmup.
To rename the people on a domain (not the domain itself), use Changing user names on active orders instead.

​
Steps in detail

1. Choose standard or premium

| You want to… | Use | Why | | -------------------------------------------------- | -------- | -------------------------------------------------- | | Replace one domain, no sending gap | Premium | Old domain stays warm 14 days; smoother handoff. | | Replace one domain, can absorb a brief pause | Standard | Lower cost, immediate cutover. | | Replace many domains at once | Cancel order, place new | Swaps are one domain at a time. |
POST /swaps takes type (standard or premium), domain_id, and replacement_domain. Same response shape for both types - only type differs. The replacement_domain must be a domain Peeker can either buy from a partner registrar (registrar source) or one the customer has already imported (imported source).
cURL
curl -X POST "https://api.peeker.ai/partner/v1/swaps" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H 'Content-Type: application/json' \
  -d '{
    "type":               "premium",
    "domain_id":          "dom_01HZX0D01…",
    "replacement_domain": "acme-fresh.com"
  }'
201 Created
{
	"data": {
		"id": "swp_01HZX0SW1A2B3C4D5E6F7G8H",
		"type": "premium",
		"domain_id": "dom_01HZX0D01A2B3C4D5E6F7G8H",
		"replacement_domain": "acme-fresh.com",
		"status": "created",
		"created_at": "2026-05-08T12:00:00Z"
	}
}
Poll GET /swaps/{id} or listen for the webhooks below.
cURL
curl -X GET "https://api.peeker.ai/partner/v1/swaps/swp_01HZX0SW…" \
  -H "Authorization: Bearer pk_test_<your-key>"

created  →  in_progress  →  completed
                       ↘  failed
                       ↘  action_required
EventFires when
swap.createdImmediately after POST /swaps accepts.
swap.in_progressWorkers picked it up.
swap.completedNew domain is live; old one detached (or kept warm for premium).
swap.failedSwap hit an unrecoverable error. Read the next swap payload via GET /swaps/{id}.
swap.action_requiredSwap is blocked on partner input (e.g. replacement domain isn’t imported).
The most common reason: the replacement domain isn’t imported yet. Run Importing domains & ordering for the replacement (just the import portion - no need for a new order), then call POST /swaps again. The original swap will resolve automatically once the replacement is verified, or you can cancel it and start fresh.
Webhook · swap.action_required
{
	"id": "evt_01HZX0EVFA2B3C4D5E6F7G8H",
	"type": "swap.action_required",
	"created_at": "2026-05-08T12:30:00Z",
	"data": {
		"id": "swp_01HZX0SW1A2B3C4D5E6F7G8H",
		"type": "premium",
		"domain_id": "dom_01HZX0D01A2B3C4D5E6F7G8H",
		"replacement_domain": "acme-fresh.com",
		"status": "action_required",
		"created_at": "2026-05-08T12:00:00Z"
	}
}

​
What’s next

Changing user names on active orders

Same domain, different people on the inboxes - for team rotations.

Best practices

Pending actions, webhook hygiene, idempotent retries.
Last modified on June 29, 2026