Operations on Stripe Subscription Item objects.
A SubscriptionItem is a single plan/price line on a Subscription. Manipulating items lets you add products, change quantities, and swap prices on a live subscription without re-creating it.
This module is at the flat top-level namespace (LatticeStripe.SubscriptionItem)
per Phase 1 D-17, matching LatticeStripe.Customer, LatticeStripe.Invoice,
and friends.
Listing requires a subscription
list/3 and stream!/3 require the "subscription" param — unfiltered
SubscriptionItem listing is an antipattern and produces confusing results
(it returns items across all subscriptions, which is rarely what you want).
Passing %{} raises ArgumentError immediately.
Usage-based billing note
Legacy Usage Records (/v1/subscription_items/:id/usage_records) are being
deprecated by Stripe in favor of the Billing Meters API (/v1/billing/meters,
/v1/billing/meter_events). Meters are not yet wired into LatticeStripe —
see roadmap BILL-07. For new integrations, use Billing Meters directly via
raw HTTP until that phase ships.
Proration
All mutations (create/3, update/4, delete/3/delete/4) run the
Billing.Guards.check_proration_required/2 guard before dispatching. If
your client sets require_explicit_proration: true, you MUST pass
"proration_behavior" in the params.
Stripe API Reference
See the Stripe Subscription Items API.
Summary
Functions
Creates a new SubscriptionItem.
Like create/3 but raises on failure.
Deletes a SubscriptionItem.
Like delete/3 but raises on failure.
Like delete/4 but raises on failure.
Converts a decoded Stripe API map to a %SubscriptionItem{} struct.
Lists SubscriptionItems filtered by subscription.
Like list/3 but raises on failure.
Retrieves a SubscriptionItem by ID.
Like retrieve/3 but raises on failure.
Lazy stream of SubscriptionItems for a given subscription.
Updates a SubscriptionItem.
Like update/4 but raises on failure.
Types
@type t() :: %LatticeStripe.SubscriptionItem{ billing_thresholds: map() | nil, created: integer() | nil, discounts: list() | nil, extra: map(), id: String.t() | nil, metadata: map() | nil, object: String.t(), plan: map() | nil, price: map() | nil, proration_behavior: String.t() | nil, quantity: integer() | nil, subscription: String.t() | nil, tax_rates: list() | nil }
A Stripe Subscription Item object.
Functions
@spec create(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Creates a new SubscriptionItem.
Sends POST /v1/subscription_items. Runs the proration guard before dispatching.
Parameters
client-%LatticeStripe.Client{}params- Map with at least"subscription"and"price". Common keys:"subscription","price","quantity","proration_behavior"opts- Per-request overrides (e.g.,[idempotency_key: "..."])
Returns
{:ok, %SubscriptionItem{}}on success{:error, %LatticeStripe.Error{}}on failure or guard rejection
@spec create!(LatticeStripe.Client.t(), map(), keyword()) :: t()
Like create/3 but raises on failure.
@spec delete(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Deletes a SubscriptionItem.
Sends DELETE /v1/subscription_items/:id with optional params such as
"clear_usage" and "proration_behavior". Runs the proration guard before
dispatching.
The 3-arity form delegates to 4-arity with empty params.
@spec delete(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
@spec delete!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like delete/3 but raises on failure.
@spec delete!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like delete/4 but raises on failure.
Converts a decoded Stripe API map to a %SubscriptionItem{} struct.
Returns nil when given nil.
id is always preserved. stripity_stripe had a well-known bug where
nested SubscriptionItems inside Subscription responses lost their id
(see issue #208), making programmatic updates impossible. This decoder
covers that case explicitly via the round-trip unit tests.
@spec list(LatticeStripe.Client.t(), map(), keyword()) :: {:ok, LatticeStripe.Response.t()} | {:error, LatticeStripe.Error.t()}
Lists SubscriptionItems filtered by subscription.
Requires "subscription" in params. Raises ArgumentError otherwise
(OQ-2: unfiltered listing is an antipattern).
@spec list!(LatticeStripe.Client.t(), map(), keyword()) :: LatticeStripe.Response.t()
Like list/3 but raises on failure.
@spec retrieve(LatticeStripe.Client.t(), String.t(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Retrieves a SubscriptionItem by ID.
@spec retrieve!(LatticeStripe.Client.t(), String.t(), keyword()) :: t()
Like retrieve/3 but raises on failure.
@spec stream!(LatticeStripe.Client.t(), map(), keyword()) :: Enumerable.t()
Lazy stream of SubscriptionItems for a given subscription.
Requires "subscription" in params.
@spec update(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: {:ok, t()} | {:error, LatticeStripe.Error.t()}
Updates a SubscriptionItem.
Runs the proration guard before dispatching.
@spec update!(LatticeStripe.Client.t(), String.t(), map(), keyword()) :: t()
Like update/4 but raises on failure.