Skip to content

API: Buying

← API overview

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 fieldTypeRequiredNotes
product_typestringnoA product_type from get_pricing. Give this or bundle_type. up to 60 chars
bundle_typestringnoA bundle_type from get_pricing. Give this or product_type. up to 60 chars
quantityintegernoUnits of the product. Ignored for a bundle. min 1, max 100000, default 1
Terminal window
curl -X POST "https://api.maildeck.co/v1/quotes" \
-H "Authorization: Bearer $MAILDECK_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'

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 fieldTypeRequiredNotes
product_typestringnoA product_type from get_pricing. Give this or bundle_type. up to 60 chars
bundle_typestringnoA bundle_type from get_pricing. Give this or product_type. up to 60 chars
quantityintegernoUnits of the product. Ignored for a bundle. min 1, max 100000, default 1
expected_due_now_centsintegeryesdue_now_cents from quote_order. min 0, max 9007199254740991
countrystringyesBilling country, ISO 3166-1 alpha-2, e.g. “US”, “DE”. up to 2 chars
vat_numberstringnoEU VAT number. Required when the billing country is in the EU. up to 30 chars
terms_acceptedbooleanyestrue once the person has read and accepted the terms at terms.url
idempotency_keystringyesAny unique string for this action. Sending the same one again returns the first result instead of repeating the action. up to 200 chars
confirmbooleanyesMust be true. Confirms the person has agreed to this action
Terminal window
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 /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.

ParameterInTypeRequiredNotes
checkout_idpathstringyescheckout_id from create_checkout
Terminal window
curl -X GET "https://api.maildeck.co/v1/checkouts/<checkout_id>" \
-H "Authorization: Bearer $MAILDECK_API_KEY"