Create or update a coupon

post

https://api.fastspring.com/coupons

Creates a new coupon or updates an existing one. The operation is
determined automatically based on whether the coupon path identifier
already exists — no separate update endpoint is required.

The action field in the response confirms which operation was
performed: coupon.create or coupon.update.

Warning: Including the codes array in an update request
permanently replaces all existing codes. Omit the codes field to
preserve existing codes.

Body Params

coupon

string

required

Unique coupon path identifier. Accepts alphanumeric characters, hyphens, and underscores only.

orderLevelDiscount

boolean

(Beta) Applies the discount to the entire order subtotal
rather than individual line items. The discount is proportionally
allocated across eligible items, excluding add-ons and fees.
Taxes are calculated after the discount is applied.

This field is part of the closed, invite-only Order-Level
Coupons beta. Only accounts enrolled in the beta can set this
field to true.

When true, the following values are server-enforced regardless
of what is sent in the request:

Field	Enforced value
`combine`	`true`
`applyDiscountImmediately`	`true`
`discountPeriodCount`	`1`

The discount.type must be flat when orderLevelDiscount
is true.

hasMultiDiscount

boolean

Enables multi-tier discount mode for tiered subscription offers.
When true, the discounts array is required in place of the
discount object. Cannot be true if orderLevelDiscount
is true.

discount

object

Discount type and amount configuration.

discounts

array of objects

length between 2 and 25

Array of multi-tier discount configurations. Required when
hasMultiDiscount is true. Tiers are automatically sorted
descending by duration.

Constraints:

Must contain between 2 and 25 tiers.
A product path may only appear in one tier.
At most one tier may omit the products array (applies to
all products).

discounts

A single discount tier within a multi-tier configuration.

type

string

enum

Discount type for this tier.

Allowed:

percent

number

Percentage amount for this tier. Required when type is percent. Decimal values are accepted.

amount

object

Per-currency flat discount amounts for this tier. Required when type is flat.

products

array of strings

Product path identifiers this tier applies to. Omit to apply this tier to all products. At most one tier per coupon may omit this field.

products

discountPeriodCount

integer

Number of billing periods this tier's discount applies to.

applyDiscountImmediately

boolean

Applies this tier's discount starting in the first billing period rather than the next renewal period.

A single discount tier within a multi-tier configuration.

type

string

enum

Discount type for this tier.

Allowed:

percent

number

Percentage amount for this tier. Required when type is percent. Decimal values are accepted.

amount

object

Per-currency flat discount amounts for this tier. Required when type is flat.

products

array of strings

Product path identifiers this tier applies to. Omit to apply this tier to all products. At most one tier per coupon may omit this field.

products

discountPeriodCount

integer

Number of billing periods this tier's discount applies to.

applyDiscountImmediately

boolean

Applies this tier's discount starting in the first billing period rather than the next renewal period.

discountPeriodCount

integer

0 to 365

Number of billing periods the discount applies to. Accepts
values from 0 to 365. 0 is treated as unlimited and
stored as null in the response.

Ignored and forced to 1 when orderLevelDiscount is true.

applyDiscountImmediately

boolean

Applies the discount starting in the first billing period rather
than the next renewal period. Requires a feature flag on your
account.

Ignored and forced to true when orderLevelDiscount is true.

combine

boolean

Allows this discount to stack with other active discounts. Forced to true when orderLevelDiscount is true.

autoSelectDiscount

boolean

Automatically selects the most favorable discount for the
customer when multiple discounts are applicable. Only applies
when combine is false. Requires a feature flag on your
account.

Note: This field is accepted without error but has no effect
until the feature flag is enabled. It is not returned in GET
responses.

reason

object

Localized description of the discount, visible to customers at
checkout. Provide each translation as a key-value pair using the
ISO 639-1 language code as the key (e.g. en, de, fr).

limit

integer

≥ 0

Maximum number of times this discount can be applied across all
customers and codes. 0 means unlimited.

Note: This value is returned as a string in GET responses.
0 sent → "" received. Both represent unlimited.

available

object

Active date range for the coupon. When omitted, the coupon has no
date restrictions. Returns {} in GET responses when not configured.

Accepted date formats for both start and end:

ISO 8601: 2026-06-01T00:00:00Z
Date only: 2026-06-01
Date and time: 2026-06-01 00:00

Validation rules:

start must not be a past date.
end must not be a past date.
end must be after start.

codes

array of strings

Coupon codes that activate this discount at checkout.

Code handling

Case: Codes are normalized to uppercase on storage.
summer10 and SUMMER10 are stored as the same code.
Duplicates: Duplicate codes within this array are
accepted without error and echoed verbatim in the response,
but storage silently dedupes (case-insensitively) to a
single entry per unique code. Call
GET /coupons/{coupon_id}/codes after the write to
confirm the stored state.
Format: Alphanumeric characters, hyphens, and
underscores only. Spaces and other special characters are
rejected.

codes

products

array of strings

Product path identifiers this discount applies to. An empty array applies the discount to all eligible products.

products

200Returned for both successful operations and validation errors. Always check the result field to determine the outcome.

400Returned when the request body contains unknown or unsupported fields. Returns DeserializationErrorResponse.