Promotion Codes

A promotion code is the customer-facing string (e.g. LAUNCH50) that maps to a Coupon. Promotion codes can scope, limit, and gate the underlying discount per identity.

Accessed via client.promotion_codes.

Methods

`create(**body)`

POST /promotion-codes. Requires coupon_id:; code: is optional (the API generates one if omitted).

client.promotion_codes.create(
  coupon_id:       "cpn_…",
  code:            "SUMMER25",
  max_redemptions: 1_000,
  expires_at:      "2026-09-01T00:00:00Z"
)

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

GET /promotion-codes.

`retrieve(id)`

GET /promotion-codes/:id.

`update(id, **body)`

PATCH /promotion-codes/:id.

client.promotion_codes.update("pc_…", active: false)

`delete(id)`

DELETE /promotion-codes/:id.

`validate(code:, identity_id: nil, amount: nil)`

POST /promotion-codes/validate. Server-side validity check before applying the code at checkout. Optionally scope the check to a specific identity and/or order amount.

result = client.promotion_codes.validate(
  code:        "SUMMER25",
  identity_id: customer[:id],
  amount:      4_900
)

Object shape

:id, :code, :coupon_id, :active, :expires_at, :max_redemptions, :times_redeemed, :restrictions, …

Examples

Validate before applying

result = client.promotion_codes.validate(code: params[:code], identity_id: customer[:id])
if result[:valid]
  client.subscriptions.apply_discount(sub[:id], promotion_code: params[:code])
else
  flash[:error] = "That code can't be used on this subscription."
end

Generate a one-shot personalised code

client.promotion_codes.create(
  coupon_id:       "cpn_winback",
  max_redemptions: 1,
  metadata:        { customer_id: customer[:id] }
)

Promotion Codes

On this page