A portfolio plan groups specific domain operations into a reviewable, durable job. Use it when you need a recorded selection, approval and per-domain outcomes across many domains. Begin with a small representative selection before planning a large customer portfolio.
| Method | Resource | Scope | Idempotency-Key |
|---|---|---|---|
POST |
/v2/portfolio/preview |
domains:read |
Required |
POST |
/v2/portfolio/jobs |
domains:operate |
Required |
01 Prepare explicit operation requests
Each item contains domain, operation and its payload. The planner recognises availability, register, renew, transfer, auto_renew, let_expire, lock, privacy, contacts, nameservers, dns_template, dns_record, domain_forwarding and reseller_push. Actual provider and account capabilities still determine which work can execute.
For example, a proposed lock request for a domain you own has this shape:
{
"requests": [
{"domain": "example.com", "operation": "lock", "payload": {"enabled": true}}
],
"chunk_size": 100
}
The selection can contain up to 10,000 operation objects. Chunk size is bounded from 1 to 500. Duplicate domain, operation and payload combinations are rejected. The planner skips register or transfer items already owned, and skips operations on unowned domains when ownership is required.
02 Review the whole plan
- POST the explicit requests to
portfolio/previewwith an idempotency key. - Inspect executable items, skipped reasons, provider grouping, risk and reversibility indicators, chunk count and approval requirement.
- Compare the selected domains with your customer inventory. Correct omissions, unintended duplicates and ownership changes before proceeding.
- Obtain current financial quotes separately for charged operations. The REST preview does not supply a complete live pricing check for every item.
- POST the reviewed requests to
portfolio/jobswith a meaningful name. The server recomputes the plan; read and review the stored job before approval.
Common questions
Does the preview change any domains?
No domain operation is executed by this preview. It also does not reserve a name, guarantee future availability or settle payment.
Can I use the DNS record helper for every existing record key?
Use the primary per-zone changeset API for exact updates or deletions. This release's portfolio DNS helper shortens record keys, which is unsuitable for relying on longer existing identifiers.
Does scheduled_at guarantee that an early start request waits?
No. It records scheduling intent in this contract. Call start only when execution is authorised and due; do not assume an explicit early start is deferred automatically.