Coupons

A coupon is a reusable discount template — percent-off or amount-off, applied once or recurring across N billing periods. Promotion codes are the customer-facing names you hand out; coupons are the underlying discount.

Accessed via client.coupons.

Methods

create(**body)

POST /coupons.

client.coupons.create(percent_off: 25, duration: "once")
client.coupons.create(amount_off: 1_000, currency: "USD", duration: "repeating", duration_in_months: 3)

list(limit: nil, offset: nil, ids: nil)

GET /coupons.

retrieve(id)

GET /coupons/:id.

update(id, **body)

PATCH /coupons/:id. Coupons are mostly immutable — the metadata and active flag are the practical update targets.

client.coupons.update("cpn_…", active: false)

delete(id)

DELETE /coupons/:id.

Object shape

:id, :percent_off, :amount_off, :currency, :duration (once, forever, repeating), :duration_in_months, :max_redemptions, :redeem_by, :active, :created_at, …

Examples

Create a one-time 25% off coupon

coupon = client.coupons.create(percent_off: 25, duration: "once")

Wrap a coupon in a customer-facing promotion code

coupon = client.coupons.create(percent_off: 50, duration: "once")
client.promotion_codes.create(coupon_id: coupon[:id], code: "LAUNCH50", max_redemptions: 100)

Retire a coupon without deleting it

client.coupons.update("cpn_…", active: false)