Skip to main content
POST
Create a coupon

Discount Units

discount_value is in dollars for Fixed (e.g. 10 = $10.00 off) and a 0-100 percentage for Percentage (e.g. 15 = 15% off) — the same units returned by GET /coupon/validate.

Usage Type

"One Time" discounts a single order. "Multiple Times" discounts all orders, including auto refills. Total redemptions across all patients are capped by maximum_redemptions.

Patient Gating

When allowed_emails or allowed_patient_ids is provided, only the listed patients can redeem the coupon at checkout. Note that GET /coupon/validate reports code validity for the store without evaluating patient gating — gating is enforced when the coupon is applied at checkout.

Authentication

This endpoint requires your secret API key (sk_), sent in the x-api-key header — not the public (pk_) key. The secret key is for server-to-server calls only; never expose it in a browser or client-side code.

Code Generation

Codes are generated server-side from an unambiguous uppercase alphabet (no O/0/I/1), e.g. K7X29MJ4Q2AB. Pass code_prefix to brand them: "ACP" produces ACP-K7X29MJ4Q2AB. The caller cannot choose the full code.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
code
string
required
discount
object
required
description
string | null
expires_at
string<date-time> | null
plan_ids
string<MeteroidId>[]
recurring_value
integer<int32> | null
redemption_limit
integer<int32> | null
reusable
boolean

Response

Coupon created

code
string
required
description
string
required
disabled
boolean
required
discount
object
required
id
string<MeteroidId>
required
Example:

"cou_7n42DGM5Tflk9n8mt7Fhc7"

reusable
boolean
required
expires_at
string<date-time> | null
recurring_value
integer<int32> | null
redemption_limit
integer<int32> | null