Get a promotion
One offer, with how many times it has been used and what it has taken off.
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
id*stringSuccess
application/json- response
Success
id*stringname*stringpriceListId*|The list the offer belongs to. Null when it covers every list
product*string"number""domain""domain_privacy""licence""mailbox"match*|What it is narrowed to within its product, or the first of matches when it names several. Null for all of it
matches*array<>|Everything it is narrowed to: one or several. 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 GET "https://example.com/v1/promotions/prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"{ "id": "prm_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "name": "Launch offer on .com", "priceListId": "prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA", "product": "number", "match": "com", "matches": [ "com", "net", "org" ], "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"}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.
Update a promotion PATCH
Send only what changes. Purchases already made keep the price they were made at, and the uses already claimed stay claimed.