Operations on Stripe Promotion Code objects.

A PromotionCode is the customer-facing form of a Coupon — it's the string a customer types at checkout (e.g., "SUMMER25USER"). Multiple PromotionCodes can share the same underlying Coupon, each with its own usage restrictions.

Identifiers

Three distinct identifiers are easy to confuse:

The customer types PromotionCode.code at checkout; the Stripe API accepts it and resolves it to the PromotionCode.id, which in turn references the underlying Coupon.

Usage

# Create a PromotionCode attached to an existing Coupon
{:ok, promo} = LatticeStripe.PromotionCode.create(client, %{
  "coupon" => "SUMMER25",
  "code" => "SUMMER25USER",
  "active" => true,
  "max_redemptions" => 100
})

# Update (deactivate)
{:ok, _} = LatticeStripe.PromotionCode.update(client, promo.id, %{"active" => "false"})

Finding promotion codes

PromotionCode has no search/3 endpoint (verified absent from Stripe's OpenAPI spec — only 7 resources have search: charges, customers, invoices, payment_intents, prices, products, subscriptions). Discover existing promotion codes via list/2 with filters:

• code — find by customer-facing code string
• coupon — all promotion codes attached to a coupon ID
• customer — promotion codes restricted to a specific customer
• active — filter to only active or inactive codes

Example:

{:ok, resp} =
  LatticeStripe.PromotionCode.list(client, %{
    "code" => "SUMMER25USER",
    "active" => "true"
  })

Operations not supported by the Stripe API

• search — The /v1/promotion_codes/search endpoint does not exist. Use list/2 with filters (see above).
• delete — PromotionCodes cannot be deleted. To deactivate, call update/4 with %{"active" => "false"}.

Stripe API Reference

See the Stripe Promotion Code API.