List promotions
Every offer you have run, newest first. An account holds at most 200 of them, so they all come back at once.
apiKeyAuthorizationBearer <token>An API key from the Developers page. rhq_test_ keys reach the sandbox, rhq_live_ keys the live side.
priceListId?stringOnly offers on this list
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"The offers you have run
application/json- response
The offers you have run
data*array<>curl -X GET "https://example.com/v1/promotions?priceListId=prl_01K6XJ4Q8ZT3M9R5V2B7WDHNCA"{ "data": [ { "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" } ]}Replace contract prices PUT
Replaces the whole set; send an empty list to clear it. Rules have the same shape as price list rules, with optional dates. `add` and `fixed` values are in the currency of the customer's list. Two rules for the same items and tier must not be in date at the same time.
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.