Coupons

A coupon is a discount template you apply to a customer, subscription, or one-off invoice. See Discounts & coupons for the model.

Object

{
  "id": "coup_…",
  "object": "coupon",
  "code": "SUMMER25",
  "type": "percent",
  "amount_off": "25",
  "currency": null,
  "duration": "repeating",
  "duration_in_months": 3,
  "max_redemptions": 1000,
  "redemption_count": 247,
  "applies_to": {
    "plan_codes": ["pro-monthly-usd"],
    "product_codes": null,
    "components": null
  },
  "valid_from": "2026-05-01T00:00:00Z",
  "valid_until": "2026-08-31T23:59:59Z",
  "metadata": {},
  "status": "active",
  "created_at": "2026-04-15T00:00:00Z"
}

Endpoints

Method	Path	What
POST	/v1/coupons	Create.
GET	/v1/coupons/{code-or-id}	Retrieve.
PATCH	/v1/coupons/{code-or-id}	Update mutable fields.
DELETE	/v1/coupons/{code-or-id}	Soft-delete.
GET	/v1/coupons	List + filter.
POST	/v1/promotion-codes	Create a public-facing promo code.
GET	/v1/promotion-codes	List promo codes.

Mutable fields

max_redemptions, valid_until, metadata, status. The discount amount itself (type, amount_off, duration) is immutable — existing redemptions hold what was promised. Create a new coupon if you need different terms.

Status

active, expired (post valid_until), archived (manually deactivated), deleted.

Webhook events

coupon.created, coupon.updated, coupon.deleted, promotion_code.redeemed.