Promotion Codes

A PromotionCode is a customer-facing code (SUMMER2026) that wraps a Coupon. Use coupons to model the discount; use promotion codes to expose it to end users with code strings, expiry dates, minimum order amounts, and redemption caps.

Namespace: client.promotion_codes.

Methods

`create`

promo = client.promotion_codes.create(
    code="SUMMER2026",
    coupon_id="cou_25_off",
    max_redemptions=500,
    expires_at="2026-09-01T00:00:00Z",
    minimum_amount=2000,
    minimum_amount_currency="USD",
    first_time_transaction=True,
    idempotency_key="promo-summer2026",
)

Returns: PromotionCode. coupon_id is required.

`list`

codes = client.promotion_codes.list(limit=50)

`retrieve`

promo = client.promotion_codes.retrieve("promo_123")

`update`

promo = client.promotion_codes.update("promo_123", active=False)

`delete`

client.promotion_codes.delete("promo_123")

`validate`

result = client.promotion_codes.validate(
    code="SUMMER2026",
    customer_id="cus_123",
    items=[{"price_id": "price_monthly", "quantity": 1}],
)

if result.valid:
    show_discount(result.discount_preview)
else:
    show_error(result.reason)

Returns: ValidatePromotionCodeResponse (valid, promotion_code, coupon, discount_preview, reason). Use this on your checkout's "Apply code" button before confirming the order.

Object shape

PromotionCode:

Field	Type
`id`	`str`
`code`	`str \| None`
`coupon_id`	`str \| None`
`active`	`bool \| None`
`max_redemptions`	`int \| None`
`times_redeemed`	`int \| None`
`expires_at`	`str \| None`
`customer_id`	`str \| None` (single-customer codes)
`minimum_amount` / `minimum_amount_currency`	`int \| None` / `str \| None`
`first_time_transaction`	`bool \| None`
`metadata`, `created_at`, `updated_at`	Standard.

ValidatePromotionCodeResponse:

Field	Type
`valid`	`bool`
`promotion_code`	`PromotionCode \| None`
`coupon`	`dict[str, Any] \| None`
`discount_preview`	`dict[str, Any] \| None`
`reason`	`str \| None`

Examples

Self-service "apply code" handler

@app.post("/api/cart/apply-code")
def apply_code(request):
    result = client.promotion_codes.validate(
        code=request.json["code"],
        customer_id=request.user.easy_customer_id,
        items=request.session["cart_items"],
    )
    return {
        "valid": result.valid,
        "preview": result.discount_preview,
        "reason": result.reason,
    }

Apply the validated code to a subscription

client.subscriptions.apply_discount(
    sub_id,
    promotion_code="SUMMER2026",
)

Disable a code without deleting it

client.promotion_codes.update("promo_123", active=False)

Promotion Codes

On this page