Preview a promotion
Takes the offer you are thinking of running and saves nothing. Says how many customers are on its list, how many things they hold, and for a sample of those what one unit costs them now and what it would cost on the offer. belowCost counts the ones that would sell under what you pay: this route reports them rather than refusing the offer, since seeing the margin is the point of it.
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
application/json- body
name*string1 <= length <= 80priceListId?|The list the offer belongs to. Null, or left out, covers every list
product*string"number""domain""domain_privacy""licence""mailbox"match?|Narrows the offer within its product. Null, or left out, covers the whole product; send null to take a narrowing off again. For several at once, send matches
matches?array<>|Narrows the offer to any of these: several domain endings, countries or plans in one promotion. Send this or match, not both; null takes the narrowing off again
term?|Narrows a number offer to one rental length. Null, or left out, covers every length
kind*stringfixed is the promotional price itself; percent takes a share off the normal price; amount takes a fixed sum off it
"fixed""percent""amount"value*integerMinor units of the list's currency for fixed and amount; basis points for percent (2500 is 25% off)
0 <= value <= 100000000startsAt*stringWhen the offer starts
date-timeendsAt*stringWhen it stops. A purchase at or after this moment pays the normal price
date-timecode?|The coupon code an order has to send. Null, or left out, and everyone on the list gets the offer without asking. A code is never handed out twice, even after the offer ends
maxUses?|How many times it may be used in all. Null, or left out, for no limit
maxPerCustomer?|How many times one customer may use it. Null, or left out, for no limit
applies?stringnew is first purchases only, which is what an introductory offer means; renew is renewals only; both is every purchase, a restore included
"new""new""renew""both"allowBelowCost?booleanLets the promotional price sit under what you pay for the item
falseid?stringThe offer being changed, so its own dates and coupon are not counted twice
What the offer would do to the prices customers on its list are charged
application/json- response
What the offer would do to the prices customers on its list are charged
customers*integerHow many customers are on the offer's list
items*integerHow many active domains, licences and numbers those customers hold
belowCost*integerHow many of the items in data would sell under what you pay
data*array<>curl -X POST "https://example.com/v1/promotions/impact" \ -H "Content-Type: application/json" \ -d '{ "name": "Launch offer on .com", "product": "number", "kind": "fixed", "value": 2500, "startsAt": "2026-10-07T11:04:31.000Z", "endsAt": "2026-12-01T00:00:00.000Z" }'{ "customers": 3, "items": 12, "belowCost": 0, "data": [ { "type": "number", "id": "dom_01K6Z3M5T8Q2W4E6R8Y0U2I4O6", "name": "northwind-telecom.com", "customerId": "cus_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "cost": 1440, "normal": { "cost": 1440, "price": 1440, "currency": "USD", "priceUsd": 1440, "ruleId": "prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "level": "override", "floored": true, "normalPrice": 1440, "discount": 1440, "promotion": { "id": "prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "code": "LAUNCH25", "endsAt": "2026-11-01T00:00:00.000Z" } }, "promoted": { "cost": 1440, "price": 1440, "currency": "USD", "priceUsd": 1440, "ruleId": "prr_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "level": "override", "floored": true, "normalPrice": 1440, "discount": 1440, "promotion": { "id": "prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "code": "LAUNCH25", "endsAt": "2026-11-01T00:00:00.000Z" } } } ]}Create a promotion POST
A price for the dates it runs, on one list or on every list. With no `code` everyone on the list gets it; with one, only an order that sends that coupon. It changes what the customer is charged and nothing else: your wallet is still charged wholesale. An offer that would have to sell under what you pay is refused unless you set `allowBelowCost`; `POST /v1/promotions/impact` shows the margin either way first.
Get a promotion GET
One offer, with how many times it has been used and what it has taken off.