Coupons

A coupon is a reusable discount template — percentage-off or fixed-amount, applied once / for N months / forever. Coupons are attached to subscriptions via applySubscriptionDiscount or surfaced to buyers through promotion codes.

Methods

easy.createCoupon(body);          // POST   /coupons
easy.listCoupons(params?);        // GET    /coupons
easy.getCoupon(couponId);         // GET    /coupons/:id
easy.updateCoupon(couponId, body); // PATCH  /coupons/:id
easy.deleteCoupon(couponId);      // DELETE /coupons/:id

CreateCoupon is a discriminated union — pass percent_off or amount_off + currency, never both:

// Percentage off
await easy.createCoupon({
  duration: "repeating",
  duration_in_months: 3,
  percent_off: 25,
  name: "Q2 promo",
  max_redemptions: 1000,
  valid_until: "2026-06-30T23:59:59Z",
  applies_to_products: ["PD_pro"],
  metadata: { campaign: "spring_2026" },
});

// Fixed amount off (smallest currency unit)
await easy.createCoupon({
  duration: "once",
  amount_off: 1000,
  currency: "USD",
  name: "$10 welcome credit",
});

UpdateCoupon is intentionally narrow — only name, active, and metadata are mutable. To change the discount itself, create a new coupon and migrate users.

Object shape

CouponData:

Field	Type	Notes
`id`	`string`
`name`	`string \| null`
`duration`	`"once" \| "repeating" \| "forever"`
`duration_in_months`	`number \| null`	Only set when `duration === "repeating"`.
`percent_off`	`number \| null`	0–100.
`amount_off`	`number \| null`	Smallest currency unit.
`currency`	`string \| null`	Required with `amount_off`.
`max_redemptions`	`number \| null`	Lifetime cap.
`times_redeemed`	`number`	Counter.
`valid_until`	`string \| null`	ISO timestamp.
`applies_to_products`	`string[] \| null`	Restrict eligibility.
`active`	`boolean`
`metadata`	`Record<string, unknown>`

Examples

Forever 50%-off VIP coupon

const coupon = await easy.createCoupon({
  duration: "forever",
  percent_off: 50,
  name: "VIP",
});

Pause a coupon without deleting redemptions

await easy.updateCoupon(couponId, { active: false });

List active coupons

const all = await easy.listCoupons({ limit: 100 });
const active = all.data.filter((c) => c.active);