Stripe.SubscriptionItem (stripity_stripe v3.3.2)

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

Summary

Types

billing_thresholds()

discounts()

price_data()

Data used to generate a new Price object inline.

recurring()

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

t()

The subscription_item type.

Functions

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

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

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

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

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

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

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

Retrieves the subscription item with the given ID.

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

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

Types

billing_thresholds()

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

discounts()

@type discounts() :: %{
  optional(:coupon) => binary(),
  optional(:discount) => binary(),
  optional(:promotion_code) => binary()
}

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(),
  current_period_end: integer(),
  current_period_start: integer(),
  discounts: term(),
  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.
current_period_end The end time of this subscription item's current billing period.
current_period_start The start time of this subscription item's current billing period.
discounts The discounts applied to the subscription item. Subscription item discounts are applied before subscription discounts. Use expand[]=discounts to expand each discount.
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(:discounts) => [discounts()] | 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(:discounts) => [discounts()] | 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}