Create a promotion campaign
Authorizations
A secret API key. Publishable keys cannot reach this API. A key may carry an expiry, and an expired key is refused exactly like an unknown one, with a 401 that names no reason; check the key's expires_at in the dashboard rather than inferring it from a response. When a merchant rolls a key's secret they choose a grace window of up to 3 days, and for its duration BOTH the new secret and the one it replaced authenticate, so an integration moves over on its own deploy schedule instead of at the instant the button is pressed. Move before the window closes: after it, the old secret is refused. Nothing else about this contract moves with a roll. The key keeps its id and its scopes, so the only thing an integration updates is the credential itself.
Headers
A unique key per logical write. Replaying a request with the same key returns the first response byte for byte instead of applying the write twice.
Body
A campaign is the shared budget and window a group of discount codes draws against. campaign_identifier and budget_type are settable HERE AND NOWHERE ELSE: both are fixed at creation, and the patch refuses them by name. budget_limit is REQUIRED rather than defaulted, because 0 means UNCAPPED. A client that omitted the key would own a campaign that can spend without bound and read a 201 as success. THE CAMPAIGN IS CREATED ACTIVE, unlike a discount. It is an empty cap until a promotion is attached, and attaching is a second call, so creating it disabled would mean every first attach produced a promotion capped by a budget that is switched off. A retry outside the idempotency window collides on the unique (store, campaign_identifier) index and answers 409 campaign_exists rather than creating a second budget.
Required on create. What a merchant recognises the budget by in their own dashboard. Never shown to a shopper.
Required on create. The campaign's permanent handle, uppercased on the way in and unique per store, so a retry outside the idempotency window answers 409 campaign_exists rather than creating a second budget. It cannot be changed afterwards.
Required on create. Says whether budget_limit and budget_used are money in minor units of the store's base currency, or a count of redemptions. Fixed at creation: the running total has already accumulated in one unit, so switching would reinterpret it rather than convert it.
spend, usage Required on create. ZERO MEANS UNCAPPED, not a campaign that can spend nothing, which is why an omitted key is refused rather than defaulted. Lowering it below budget_used on a patch stops every linked discount at checkout immediately and tells nobody.
x >= 0Merchant notes. Never shown to a shopper.
Before this instant the budget guard refuses every draw, so linked discounts do not apply. Omit, or send null on a patch, for no lower bound.
After this instant the budget guard refuses every draw. Omit, or send null on a patch, to let the campaign run indefinitely.
Response
Created