View Source Stripe.Price (stripity_stripe v3.1.1)

Prices define the unit cost, currency, and (optional) billing cycle for both recurring and one-time purchases of products. Products help you track inventory or provisioning, and prices help you track payment terms. Different physical goods or levels of service should be represented by products, and pricing options should be represented by prices. This approach lets you change prices without having to change your provisioning scheme.

For example, you might have a single "gold" product that has prices for $10/month, $100/year, and €9 once.

Related guides: Set up a subscription, create an invoice, and more about products and prices.

Link to this section Summary

Types

When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links.

These fields can be used to create a new product that this price will belong to.

t()

The price type.

Apply a transformation to the reported usage or set quantity before computing the billed price. Cannot be combined with tiers.

Functions

Creates a new price for an existing product. The price can be recurring or one-time.

Returns a list of your active prices, excluding inline prices. For the list of inactive prices, set active to false.

Retrieves the price with the given ID.

Search for prices you’ve previously created using Stripe’s Search Query Language.Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged.

Link to this section Types

@type created() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}
@type custom_unit_amount() :: %{
  optional(:enabled) => boolean(),
  optional(:maximum) => integer(),
  optional(:minimum) => integer(),
  optional(:preset) => integer()
}

When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links.

@type product_data() :: %{
  optional(:active) => boolean(),
  optional(:id) => binary(),
  optional(:metadata) => %{optional(binary()) => binary()},
  optional(:name) => binary(),
  optional(:statement_descriptor) => binary(),
  optional(:tax_code) => binary(),
  optional(:unit_label) => binary()
}

These fields can be used to create a new product that this price will belong to.

@type recurring() :: %{
  optional(:interval) => :day | :month | :week | :year,
  optional(:usage_type) => :licensed | :metered
}
@type t() :: %Stripe.Price{
  active: boolean(),
  billing_scheme: binary(),
  created: integer(),
  currency: binary(),
  currency_options: term(),
  custom_unit_amount: term() | nil,
  id: binary(),
  livemode: boolean(),
  lookup_key: binary() | nil,
  metadata: term(),
  nickname: binary() | nil,
  object: binary(),
  product: binary() | Stripe.Product.t() | Stripe.DeletedProduct.t(),
  recurring: term() | nil,
  tax_behavior: binary() | nil,
  tiers: term(),
  tiers_mode: binary() | nil,
  transform_quantity: term() | nil,
  type: binary(),
  unit_amount: integer() | nil,
  unit_amount_decimal: binary() | nil
}

The price type.

  • active Whether the price can be used for new purchases.
  • billing_scheme Describes how to compute the price per period. Either per_unit or tiered. per_unit indicates that the fixed amount (specified in unit_amount or unit_amount_decimal) will be charged per unit in quantity (for prices with usage_type=licensed), or per unit of total usage (for prices with usage_type=metered). tiered indicates that the unit pricing will be computed using a tiering strategy as defined using the tiers and tiers_mode attributes.
  • created Time at which the object was created. Measured in seconds since the Unix epoch.
  • currency Three-letter ISO currency code, in lowercase. Must be a supported currency.
  • currency_options Prices defined in each available currency option. Each key must be a three-letter ISO currency code and a supported currency.
  • custom_unit_amount When set, provides configuration for the amount to be adjusted by the customer during Checkout Sessions and Payment Links.
  • id Unique identifier for the object.
  • livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
  • lookup_key A lookup key used to retrieve prices dynamically from a static string. This may be up to 200 characters.
  • 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.
  • nickname A brief description of the price, hidden from customers.
  • object String representing the object's type. Objects of the same type share the same value.
  • product The ID of the product this price is associated with.
  • recurring The recurring components of a price such as interval and usage_type.
  • tax_behavior Only required if a default tax behavior was not provided in the Stripe Tax settings. Specifies whether the price is considered inclusive of taxes or exclusive of taxes. One of inclusive, exclusive, or unspecified. Once specified as either inclusive or exclusive, it cannot be changed.
  • tiers Each element represents a pricing tier. This parameter requires billing_scheme to be set to tiered. See also the documentation for billing_scheme.
  • tiers_mode Defines if the tiering price should be graduated or volume based. In volume-based tiering, the maximum quantity within a period determines the per unit price. In graduated tiering, pricing can change as the quantity grows.
  • transform_quantity Apply a transformation to the reported usage or set quantity before computing the amount billed. Cannot be combined with tiers.
  • type One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.
  • unit_amount The unit amount in cents (or local equivalent) to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit.
  • unit_amount_decimal The unit amount in cents (or local equivalent) to be charged, represented as a decimal string with at most 12 decimal places. Only set if billing_scheme=per_unit.
@type tiers() :: %{
  optional(:flat_amount) => integer(),
  optional(:flat_amount_decimal) => binary(),
  optional(:unit_amount) => integer(),
  optional(:unit_amount_decimal) => binary(),
  optional(:up_to) => :inf | integer()
}
@type transform_quantity() :: %{
  optional(:divide_by) => integer(),
  optional(:round) => :down | :up
}

Apply a transformation to the reported usage or set quantity before computing the billed price. Cannot be combined with tiers.

Link to this section Functions

Link to this function

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

View Source
@spec create(
  params :: %{
    optional(:active) => boolean(),
    optional(:billing_scheme) => :per_unit | :tiered,
    optional(:currency) => binary(),
    optional(:currency_options) => map(),
    optional(:custom_unit_amount) => custom_unit_amount(),
    optional(:expand) => [binary()],
    optional(:lookup_key) => binary(),
    optional(:metadata) => %{optional(binary()) => binary()},
    optional(:nickname) => binary(),
    optional(:product) => binary(),
    optional(:product_data) => product_data(),
    optional(:recurring) => recurring(),
    optional(:tax_behavior) => :exclusive | :inclusive | :unspecified,
    optional(:tiers) => [tiers()],
    optional(:tiers_mode) => :graduated | :volume,
    optional(:transfer_lookup_key) => boolean(),
    optional(:transform_quantity) => transform_quantity(),
    optional(:unit_amount) => integer(),
    optional(:unit_amount_decimal) => binary()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Creates a new price for an existing product. The price can be recurring or one-time.

Details

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

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

View Source
@spec list(
  params :: %{
    optional(:active) => boolean(),
    optional(:created) => created() | integer(),
    optional(:currency) => binary(),
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:lookup_keys) => [binary()],
    optional(:product) => binary(),
    optional(:recurring) => recurring(),
    optional(:starting_after) => binary(),
    optional(:type) => :one_time | :recurring
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Returns a list of your active prices, excluding inline prices. For the list of inactive prices, set active to false.

Details

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

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

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

Retrieves the price with the given ID.

Details

  • Method: get
  • Path: /v1/prices/{price}
Link to this function

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

View Source
@spec search(
  params :: %{
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:page) => binary(),
    optional(:query) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.SearchResult.t(t())}
  | {:error, Stripe.ApiErrors.t()}
  | {:error, term()}

Search for prices you’ve previously created using Stripe’s Search Query Language.Don’t use search in read-after-write flows where strict consistency is necessary. Under normal operating conditions, data is searchable in less than a minute. Occasionally, propagation of new or updated data can be up to an hour behind during outages. Search functionality is not available to merchants in India.

#### Details * Method: `get` * Path: `/v1/prices/search`

Link to this function

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

View Source
@spec update(
  price :: binary(),
  params :: %{
    optional(:active) => boolean(),
    optional(:currency_options) => map() | binary(),
    optional(:expand) => [binary()],
    optional(:lookup_key) => binary(),
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:nickname) => binary(),
    optional(:tax_behavior) => :exclusive | :inclusive | :unspecified,
    optional(:transfer_lookup_key) => boolean()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged.

Details

  • Method: post
  • Path: /v1/prices/{price}