Create Discount
Create a discount for your account.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request body for creating a discount.
code is optional; if not provided, we generate a random 16-char code.
The discount amount in basis points (e.g. 540 means 5.4%, 10000 means 100%).
Must be at least 1.
The discount type: percentage or flat (flat_per_unit stays blocked).
flat, percentage Optionally supply a code (will be uppercased).
- Must be at least 3 characters if provided.
- If omitted, a random 16-character code is generated.
Per-currency options (flat deduction / percentage cap + minimum subtotal).
Required for flat codes (must include a resolvable default); optional
per-currency caps for percentage codes. Per-row invariants are checked
in normalize_currency_options, not via #[validate(nested)].
Who may redeem this discount code. Defaults to any (unrestricted).
specific starts with zero attached customers (fails closed) until
customers are attached via POST /discounts/{id}/customers.
any, first_time, existing, specific When the discount expires, if ever.
Additional metadata for the discount
Maximum number of times a single customer may redeem this discount.
Must be <= usage_limit when both are set.
Whether this discount should be preserved when a subscription changes plans. Default: false (discount is removed on plan change)
List of product IDs to restrict usage (if any).
When the discount becomes active, if scheduled for the future.
NULL = active immediately. Must be strictly before expires_at when both are set.
Number of subscription billing cycles this discount is valid for. If not provided, the discount will be applied indefinitely to all recurring payments related to the subscription.
How many times this discount can be used (if any). Must be >= 1 if provided.
Response
Created discount
The discount amount in basis points (e.g., 540 => 5.4%).
The business this discount belongs to.
The discount code (up to 16 chars).
Timestamp when the discount is created
Who may redeem this discount code.
any, first_time, existing, specific The unique discount ID
Arbitrary key-value metadata. Values can be string, integer, number, or boolean.
Whether this discount should be preserved when a subscription changes plans. Default: false (discount is removed on plan change)
List of product IDs to which this discount is restricted.
How many times this discount has been used.
The type of discount (percentage or flat).
flat, percentage Per-currency options (flat deduction / percentage cap + minimum subtotal). Empty for discounts without any configured currency options.
Optional date/time after which discount is expired.
Name for the Discount
Maximum number of times a single customer may redeem this discount, if any.
Optional date/time before which the discount is not yet active. NULL = active immediately.
Number of subscription billing cycles this discount is valid for. If not provided, the discount will be applied indefinitely to all recurring payments related to the subscription.
Usage limit for this discount, if any.