---
title: "Preview a domain-slot purchase"
method: POST
path: "/api/v1/billing/domain-slots/preview"
tags: ["Purchase"]
---

# Preview a domain-slot purchase

`POST /api/v1/billing/domain-slots/preview`

## Request

- Base URL: `https://api.aerosend.io`
- URL: `https://api.aerosend.io/api/v1/billing/domain-slots/preview`
- Auth: API key in header `X-API-Key`

Returns the price and flow for adding domain slots for the authenticated client. Does not charge.

## Behavior
- Send `domain_slots` and/or `mailbox_slots`. 1 domain slot = 3 mailboxes
- Both fields are accepted only when they match that ratio
- Existing subscription (`flow=update`) returns proration for the saved card
- No subscription (`flow=create`) returns a catalog estimate

## Response
- Returns `proration_amount` and `upcoming_invoice_amount`
- To charge or open checkout, use `POST /api/v1/billing/domain-slots`

## Request body

- DomainSlotPurchaseRequest: Buy domain slots. Send domain_slots and/or mailbox_slots (3 mailboxes per domain slot).
  - `domain_slots` integer: Domain slots to add. Min 10, step 10, max 100.
  - `mailbox_slots` integer: Mailbox slots to add. Must be domain_slots × 3 (30, 60, ... 300).

## Response `200`

Preview ready

- DomainSlotPurchaseApiResponse
  - `success` boolean: Success flag
  - `data` DomainSlotPurchaseResponse: Preview or result of a domain-slot purchase
    - `flow` string: update charges the saved card. create returns a checkout URL.
    - `charged_immediately` boolean: True when the saved card was charged immediately
    - `domain_slots` integer: Domain slots in this purchase
    - `mailbox_slots` integer: Mailbox slots in this purchase (domain_slots × 3)
    - `unit_price` number, double: Per-mailbox unit price in currency_code
    - `currency_code` string: Currency code
    - `proration_amount` number, double: Amount due now (proration for update, estimate for create)
    - `upcoming_invoice_amount` number, double: Recurring amount after this change (update flow)
    - `checkout_url` string: Pay page. Set on create purchase only.
    - `message` string: What the caller should do next
  - `timestamp` string: Response timestamp

## Other responses

- `400`: Invalid quantity
- `401`: Unauthorized - Invalid or expired API key
- `429`: Rate limit exceeded

---

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