Create a promotion
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.
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"match?|Narrows the offer within its product. Null, or left out, covers the whole product; send null to take a 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
falseCreated
application/json- response
Created
id*stringname*stringpriceListId*|The list the offer belongs to. Null when it covers every list
product*string"number""domain""domain_privacy""licence"match*|What it is narrowed to within its product. Null for all of it
term*|The rental length it is narrowed to. Null for every length
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""renew""both"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*stringdate-timeendsAt*stringdate-timecode*|The coupon code an order has to send. Null when everyone on the list gets the offer
maxUses*|How many times it may be used in all. Null for no limit
maxPerCustomer*|How many times one customer may use it. Null for no limit
allowBelowCost*booleanLets the promotional price sit under what you pay for the item
status*stringscheduled has not started, live is running now, ended is past its dates and used_up has been used as often as it allows
"scheduled""live""ended""used_up"uses*integerHow many times it has been used
discountUsd*integerWhat it has taken off in all, in US cents
0 <= valuecreatedAt*stringdate-timeupdatedAt*stringdate-timecurl -X POST "https://example.com/v1/promotions" \ -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" }'{ "id": "prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "name": "Launch offer on .com", "priceListId": "prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "product": "number", "match": "com", "term": "30d", "applies": "new", "kind": "fixed", "value": 2500, "startsAt": "2026-10-07T11:04:31.000Z", "endsAt": "2026-12-01T00:00:00.000Z", "code": "LAUNCH25", "maxUses": 100, "maxPerCustomer": 1, "allowBelowCost": true, "status": "scheduled", "uses": 12, "discountUsd": 1440, "createdAt": "2026-10-07T11:04:31.000Z", "updatedAt": "2026-10-07T11:04:31.000Z"}List promotions GET
Every offer you have run, newest first. An account holds at most 200 of them, so they all come back at once.
Preview a promotion POST
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.