LatticeStripe.Coupon (LatticeStripe v1.7.4)

Copy Markdown View Source

Operations on Stripe Coupon objects.

A Coupon is a discount template — it does not become "applied" until it is attached to a Customer, Subscription, or Invoice, at which point Stripe materialises a Discount record referencing the Coupon. Coupons are immutable by design: once created, the discount terms cannot change.

Usage

client = LatticeStripe.Client.new!(api_key: "sk_test_...", finch: MyApp.Finch)

# Auto-generated ID
{:ok, coupon} = LatticeStripe.Coupon.create(client, %{
  "percent_off" => 25,
  "duration" => "once"
})

# Custom ID (D-07 pass-through)
{:ok, coupon} = LatticeStripe.Coupon.create(client, %{
  "id" => "SUMMER25",
  "percent_off" => 25,
  "duration" => "once"
})

Custom IDs

Pass the desired ID directly in the params map as "id". The SDK performs no client-side validation — malformed IDs flow through as Stripe errors. Stripe's charset and length constraints are the server's contract.

Operations not supported by the Stripe API

  • update — Coupons are immutable by design. To change coupon terms, create a new Coupon with the new parameters and attach it to fresh discount records.
  • search — The /v1/coupons/search endpoint does not exist in Stripe's API. Use list/2 with filters for discovery.

Stripe API Reference

See the Stripe Coupon API.

Summary

Types

t()

Functions

create(client, params \\ %{}, opts \\ [])

Creates a Coupon. POST /v1/coupons. Pass "id" in params for a custom ID (D-07).

create!(c, p \\ %{}, o \\ [])
delete(client, id, opts \\ [])

Deletes a Coupon by ID. DELETE /v1/coupons/:id.

delete!(c, id, o \\ [])
from_map(map)
list(client, params \\ %{}, opts \\ [])

Lists Coupons with optional filters. GET /v1/coupons.

list!(c, p \\ %{}, o \\ [])
retrieve(client, id, opts \\ [])

Retrieves a Coupon by ID. GET /v1/coupons/:id.

retrieve!(c, id, o \\ [])
stream!(client, params \\ %{}, opts \\ [])

Types

t()

@type t() :: %LatticeStripe.Coupon{
  amount_off: integer() | nil,
  applies_to: LatticeStripe.Coupon.AppliesTo.t() | nil,
  created: integer() | nil,
  currency: String.t() | nil,
  currency_options: map() | nil,
  deleted: boolean(),
  duration: :forever | :once | :repeating | String.t() | nil,
  duration_in_months: integer() | nil,
  extra: map(),
  id: String.t() | nil,
  livemode: boolean() | nil,
  max_redemptions: integer() | nil,
  metadata: map() | nil,
  name: String.t() | nil,
  object: String.t(),
  percent_off: float() | nil,
  redeem_by: integer() | nil,
  times_redeemed: integer() | nil,
  valid: boolean() | nil
}

Functions

create(client, params \\ %{}, opts \\ [])

@spec create(LatticeStripe.Client.t(), map(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Creates a Coupon. POST /v1/coupons. Pass "id" in params for a custom ID (D-07).

create!(c, p \\ %{}, o \\ [])

delete(client, id, opts \\ [])

@spec delete(LatticeStripe.Client.t(), String.t(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Deletes a Coupon by ID. DELETE /v1/coupons/:id.

delete!(c, id, o \\ [])

from_map(map)

@spec from_map(map()) :: t()

list(client, params \\ %{}, opts \\ [])

@spec list(LatticeStripe.Client.t(), map(), keyword()) ::
  {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}

Lists Coupons with optional filters. GET /v1/coupons.

list!(c, p \\ %{}, o \\ [])

retrieve(client, id, opts \\ [])

@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) ::
  {:ok, t()} | {:error, LatticeStripe.Error.t()}

Retrieves a Coupon by ID. GET /v1/coupons/:id.

retrieve!(c, id, o \\ [])

stream!(client, params \\ %{}, opts \\ [])

@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()