View Source Stripe.SubscriptionItem (stripity_stripe v3.1.1)

Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships.

Link to this section Summary

Types

Data used to generate a new Price object inline.

The recurring components of a price such as interval and interval_count.

t()

The subscription_item type.

Functions

Adds a new item to an existing subscription. No existing items will be changed or replaced.

Deletes an item from the subscription. Removing a subscription item from a subscription will not cancel the subscription.

Returns a list of your subscription items for a given subscription.

Retrieves the subscription item with the given ID.

Updates the plan or quantity of an item on a current subscription.

For the specified subscription item, returns a list of summary objects. Each object in the list provides usage information that’s been summarized from multiple usage records and over a subscription billing period (e.g., 15 usage records in the month of September).

Link to this section Types

@type billing_thresholds() :: %{optional(:usage_gte) => integer()}
@type price_data() :: %{
  optional(:currency) => binary(),
  optional(:product) => binary(),
  optional(:recurring) => recurring(),
  optional(:tax_behavior) => :exclusive | :inclusive | :unspecified,
  optional(:unit_amount) => integer(),
  optional(:unit_amount_decimal) => binary()
}

Data used to generate a new Price object inline.

@type recurring() :: %{
  optional(:interval) => :day | :month | :week | :year,
  optional(:interval_count) => integer()
}

The recurring components of a price such as interval and interval_count.

@type t() :: %Stripe.SubscriptionItem{
  billing_thresholds: term() | nil,
  created: integer(),
  id: binary(),
  metadata: term(),
  object: binary(),
  plan: Stripe.Plan.t(),
  price: Stripe.Price.t(),
  quantity: integer(),
  subscription: binary(),
  tax_rates: term() | nil
}

The subscription_item type.

  • billing_thresholds Define thresholds at which an invoice will be sent, and the related subscription advanced to a new billing period
  • created Time at which the object was created. Measured in seconds since the Unix epoch.
  • id Unique identifier for the object.
  • metadata Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  • object String representing the object's type. Objects of the same type share the same value.
  • plan
  • price
  • quantity The quantity of the plan to which the customer should be subscribed.
  • subscription The subscription this subscription_item belongs to.
  • tax_rates The tax rates which apply to this subscription_item. When set, the default_tax_rates on the subscription do not apply to this subscription_item.

Link to this section Functions

Link to this function

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

View Source
@spec create(
  params :: %{
    optional(:billing_thresholds) => billing_thresholds() | binary(),
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:payment_behavior) =>
      :allow_incomplete
      | :default_incomplete
      | :error_if_incomplete
      | :pending_if_incomplete,
    optional(:plan) => binary(),
    optional(:price) => binary(),
    optional(:price_data) => price_data(),
    optional(:proration_behavior) =>
      :always_invoice | :create_prorations | :none,
    optional(:proration_date) => integer(),
    optional(:quantity) => integer(),
    optional(:subscription) => binary(),
    optional(:tax_rates) => [binary()] | binary()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Adds a new item to an existing subscription. No existing items will be changed or replaced.

Details

  • Method: post
  • Path: /v1/subscription_items
Link to this function

delete(item, params \\ %{}, opts \\ [])

View Source
@spec delete(
  item :: binary(),
  params :: %{
    optional(:clear_usage) => boolean(),
    optional(:proration_behavior) =>
      :always_invoice | :create_prorations | :none,
    optional(:proration_date) => integer()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.DeletedSubscriptionItem.t()}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

Deletes an item from the subscription. Removing a subscription item from a subscription will not cancel the subscription.

Details

  • Method: delete
  • Path: /v1/subscription_items/{item}
Link to this function

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

View Source
@spec list(
  params :: %{
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary(),
    optional(:subscription) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Returns a list of your subscription items for a given subscription.

Details

  • Method: get
  • Path: /v1/subscription_items
Link to this function

retrieve(item, params \\ %{}, opts \\ [])

View Source
@spec retrieve(
  item :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieves the subscription item with the given ID.

Details

  • Method: get
  • Path: /v1/subscription_items/{item}
Link to this function

update(item, params \\ %{}, opts \\ [])

View Source
@spec update(
  item :: binary(),
  params :: %{
    optional(:billing_thresholds) => billing_thresholds() | binary(),
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:off_session) => boolean(),
    optional(:payment_behavior) =>
      :allow_incomplete
      | :default_incomplete
      | :error_if_incomplete
      | :pending_if_incomplete,
    optional(:plan) => binary(),
    optional(:price) => binary(),
    optional(:price_data) => price_data(),
    optional(:proration_behavior) =>
      :always_invoice | :create_prorations | :none,
    optional(:proration_date) => integer(),
    optional(:quantity) => integer(),
    optional(:tax_rates) => [binary()] | binary()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Updates the plan or quantity of an item on a current subscription.

Details

  • Method: post
  • Path: /v1/subscription_items/{item}
Link to this function

usage_record_summaries(subscription_item, params \\ %{}, opts \\ [])

View Source
@spec usage_record_summaries(
  subscription_item :: binary(),
  params :: %{
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(Stripe.UsageRecordSummary.t())}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

For the specified subscription item, returns a list of summary objects. Each object in the list provides usage information that’s been summarized from multiple usage records and over a subscription billing period (e.g., 15 usage records in the month of September).

The list is sorted in reverse-chronological order (newest first). The first list item represents the most current usage period that hasn’t ended yet. Since new usage records can still be added, the returned summary information for the subscription item’s ID should be seen as unstable until the subscription billing period ends.

Details

  • Method: get
  • Path: /v1/subscription_items/{subscription_item}/usage_record_summaries