Coupons
Coupons — methods, parameters, and examples for easy-sdk (pip).
A Coupon is a reusable discount template — a flat amount or a
percentage off, optionally limited by duration, redemption count, or a
redeem-by date. Coupons are applied to subscriptions either directly
(subscription.apply_discount(coupon_id=...)) or wrapped in a
Promotion Code for end-user-facing flows.
Namespace: client.coupons.
Methods
create
# Percentage off
coupon = client.coupons.create(
name="25% off",
percent_off=25,
duration="forever",
idempotency_key="coupon-25-forever",
)
# Flat-amount off (one currency)
coupon = client.coupons.create(
name="$10 off",
amount_off=1000,
currency="USD",
duration="once",
)
# Time-boxed
coupon = client.coupons.create(
name="Spring promo",
percent_off=15,
duration="repeating",
duration_in_months=3,
redeem_by="2026-06-01T00:00:00Z",
max_redemptions=500,
)Pass exactly one of percent_off or amount_off. Returns: Coupon.
list
coupons = client.coupons.list(limit=50, offset=0)retrieve
coupon = client.coupons.retrieve("cou_123")update
coupon = client.coupons.update("cou_123", name="25% off (legacy)")Most fields are immutable on the server — typically you'll only update
the display name and metadata.
delete
client.coupons.delete("cou_123")Object shape
Coupon:
| Field | Type |
|---|---|
id | str |
name, code | str | None |
duration | str | None ("once", "forever", "repeating") |
duration_in_months | int | None |
amount_off | int | None |
percent_off | float | None |
currency | str | None |
max_redemptions | int | None |
times_redeemed | int | None |
redeem_by | str | None (ISO-8601) |
valid | bool | None |
metadata, created_at, updated_at | Standard. |
Examples
Apply a coupon to an existing subscription
discount = client.subscriptions.apply_discount(
"sub_123",
coupon_id="cou_25_off",
)Time-boxed campaign that auto-expires
client.coupons.create(
name="Black Friday 2026",
percent_off=30,
duration="once",
redeem_by="2026-12-01T08:00:00Z",
max_redemptions=1000,
)