# API: Buying

> Buying operations of the Maildeck API: quote_order, create_checkout, get_checkout.

Source: https://docs.maildeck.co/api/buying/

[← API overview](https://docs.maildeck.co/api/)

## quote_order

`POST /v1/quotes` · scope: **billing** · MCP tool: `quote_order`

Price an order exactly, without creating anything.

Returns what create_checkout would charge for this account, including any negotiated rate and the volume tier the account lands in. Pass due_now_cents to create_checkout as expected_due_now_cents. Show the person the price and the terms link before going further.

| Body field | Type | Required | Notes |
|---|---|---|---|
| `product_type` | string | no | A product_type from get_pricing. Give this or bundle_type. up to 60 chars |
| `bundle_type` | string | no | A bundle_type from get_pricing. Give this or product_type. up to 60 chars |
| `quantity` | integer | no | Units of the product. Ignored for a bundle. min 1, max 100000, default `1` |

```bash
curl -X POST "https://api.maildeck.co/v1/quotes" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## create_checkout

`POST /v1/checkouts` · scope: **billing** · MCP tool: `create_checkout`

Create a payment link for a plan. A person opens it and pays; nothing is charged by this call.

Opens a checkout for the quoted order and returns checkout_url. Give that link to the person: payment happens on the hosted page, never through the API. Requires the amount from quote_order (the call fails if the price changed), the billing country, an EU VAT number for EU businesses, and terms_accepted: true once the person has agreed to the terms. After payment the order waits for setup: poll get_checkout, then use update_order_setup.

| Body field | Type | Required | Notes |
|---|---|---|---|
| `product_type` | string | no | A product_type from get_pricing. Give this or bundle_type. up to 60 chars |
| `bundle_type` | string | no | A bundle_type from get_pricing. Give this or product_type. up to 60 chars |
| `quantity` | integer | no | Units of the product. Ignored for a bundle. min 1, max 100000, default `1` |
| `expected_due_now_cents` | integer | yes | due_now_cents from quote_order. min 0, max 9007199254740991 |
| `country` | string | yes | Billing country, ISO 3166-1 alpha-2, e.g. "US", "DE". up to 2 chars |
| `vat_number` | string | no | EU VAT number. Required when the billing country is in the EU. up to 30 chars |
| `terms_accepted` | boolean | yes | true once the person has read and accepted the terms at terms.url |
| `idempotency_key` | string | yes | Any unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars |
| `confirm` | boolean | yes | Must be true. Confirms the person has agreed to this action |

```bash
curl -X POST "https://api.maildeck.co/v1/checkouts" \
  -H "Authorization: Bearer $MAILDECK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_due_now_cents":1,"country":"…","terms_accepted":"…","idempotency_key":"a-unique-string","confirm":true}'
```

## get_checkout

`GET /v1/checkouts/{checkout_id}` · scope: **read** · MCP tool: `get_checkout`

Has the payment link been paid yet? Returns the order once it has.

status is "awaiting_payment" until the person pays, then "paid" with order_id and the setup checklist. Poll every 5 to 10 seconds while the person is paying; payment confirmation can take up to a minute.

| Parameter | In | Type | Required | Notes |
|---|---|---|---|---|
| `checkout_id` | path | string | yes | checkout_id from create_checkout |

```bash
curl -X GET "https://api.maildeck.co/v1/checkouts/<checkout_id>" \
  -H "Authorization: Bearer $MAILDECK_API_KEY"
```
