View Source Stripe.SubscriptionItem (stripity_stripe v3.2.0)

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).

Types

billing_thresholds()

@type billing_thresholds() :: %{optional(:usage_gte) => integer()}

price_data()

@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.

recurring()

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

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

t()

@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.

Functions

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

@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

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

@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}

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

@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

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

@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}

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

@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}

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

@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()}

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