Developer Hub
Sign In

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
string
required

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

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:

FieldEnforced value
combinetrue
applyDiscountImmediatelytrue
discountPeriodCount1

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

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.

string
enum

Discount type for this tier.

Allowed:
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
integer

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

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.

string
enum

Discount type for this tier.

Allowed:
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
integer

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

boolean

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

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.

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.

boolean

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

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).

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
Responses

Updated 15 days ago

Language
Credentials
Basic
base64
:
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 15 days ago