---
title: "Purchase several pre-warmed domains as one order"
method: POST
path: "/v1/prewarmed/purchase-batch"
tags: ["Pre-warmed Marketplace"]
---

# Purchase several pre-warmed domains as one order

`POST /v1/prewarmed/purchase-batch`

## Request

- Base URL: `https://api.winnr.app`
- URL: `https://api.winnr.app/v1/prewarmed/purchase-batch`
- Auth: HTTP bearer

Buys up to 25 pre-warmed domains as a single order with a **single charge**.
This is the endpoint to use for programmatic buying: one card charge per
order instead of one per domain.

All-or-nothing. Every domain is claimed up front; if any domain cannot be
claimed or the charge fails, the whole order is rolled back (claims
released, documents deleted, subscription quantity reverted) and you are not
billed.

Per-item rules are identical to `POST /v1/prewarmed/purchase`, including
custom-address mode.

## Request body

- PrewarmedBatchPurchaseRequest
  - `items` PrewarmedPurchaseRequest[], required: Domains to buy in this order. Duplicate domains are rejected.
    - `domain` string, required: Pre-warmed domain to purchase. Normalized to lowercase.
    - `address_count` integer, required: How many of the domain's existing warmed addresses to take. Ignored when `custom_usernames` is supplied (the count is derived from that list).
    - `custom_usernames` string[], nullable: Optional. Custom-address mode: 3 to 10 unique local-parts to provision as NEW mailboxes on the warmed domain. The warmed sample addresses are dropped. Provisioning is asynchronous.

## Response `200`

Order completed

- PrewarmedBatchPurchaseResponse
  - `data` object
    - `status` 'sold'
    - `domains` string[]: Domains purchased by this call.
    - `already_provisioned_domains` string[]: Domains in the order your account already owned; not charged again.
    - `total_address_count` integer: Addresses purchased across the whole order.
    - `minimum_term_end` string, date-time, nullable: Always null — the minimum term was removed in August 2026.
    - `invoice_id` string, nullable: The single invoice covering the first month of the whole order.
  - `meta` Meta
    - `request_id` string
    - `timestamp` string, date-time

## Other responses

- `400`: Duplicate domains in the order, an infrastructure domain, or insufficient inventory on an item. No plan subscription is required — a missing payment method returns 402 `payment_method_required` instead.
- `401`: Authentication required or token invalid
- `403`: The pre-warmed marketplace is not enabled for this account
- `404`: Resource not found
- `409`: One of the domains was claimed by another buyer; no domain in the order was purchased.

---

[API](https://skmtc.dev/winnr/apis/winnr-api.md) · [All operations](https://skmtc.dev/winnr/apis/winnr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/winnr/apis/winnr-api/revisions/a4f960beb1eb?raw)