Prices

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.

Endpoints

The Price object

Attributes

idstring
Unique identifier for the object.

activeboolean
Whether the price can be used for new purchases.

currencyenum
Three-letter ISO currency code, in lowercase. Must be a supported currency.

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

nicknamenullable string
A brief description of the price, hidden from customers.

productstringExpandable
The ID of the product this price is associated with.

recurringnullable dictionary
The recurring components of a price such as interval and usage_type.

typeenum
One of one_time or recurring depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.
Possible enum values
one_time
recurring

unit_amountnullable integer
The unit amount in cents to be charged, represented as a whole integer if possible. Only set if billing_scheme=per_unit.

More attributes

objectstring

billing_schemeenum

createdtimestamp

currency_optionsnullable dictionaryExpandable

custom_unit_amountnullable dictionary

livemodeboolean

lookup_keynullable string

tax_behaviornullable enum

tiersnullable array of dictionariesExpandable

tiers_modenullable enum

transform_quantitynullable dictionary

unit_amount_decimalnullable decimal string

The Price object

{
  "id": "price_1MoBy5LkdIwHu7ixZhnattbh",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1679431181,
  "currency": "usd",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": null,
  "product": "prod_NZKdYqrwEYx6iK",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

Create a price

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

Parameters

currencyenumRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency.

activeboolean
Whether the price can be used for new purchases. Defaults to true.

metadatadictionary
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

nicknamestring
A brief description of the price, hidden from customers.

productstringRequired unless product_data is provided
The ID of the product that this price will belong to.

recurringdictionary
The recurring components of a price such as interval and usage_type.

unit_amountintegerRequired conditionally
A positive integer in cents (or 0 for a free price) representing how much to charge. One of unit_amount or custom_unit_amount is required, unless billing_scheme=tiered.

More parameters

billing_schemeenum

currency_optionsdictionary

custom_unit_amountdictionaryRequired unless unit_amount is provided

lookup_keystring

product_datadictionaryRequired unless product is provided

tax_behaviorenum

tiersarray of dictionariesRequired if billing_scheme=tiered

tiers_modeenumRequired if billing_scheme=tiered

transfer_lookup_keyboolean

transform_quantitydictionary

unit_amount_decimalstring

Returns

The newly created Price object is returned upon success. Otherwise, this call raises an error.

POST /v1/prices

Server-side language

import stripe
stripe.api_key = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"
stripe.Price.create(
  currency="usd",
  unit_amount=1000,
  recurring={"interval": "month"},
  product_data={"name": "Gold Plan"},
)

Response

{
  "id": "price_1MoBy5LkdIwHu7ixZhnattbh",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1679431181,
  "currency": "usd",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": null,
  "product": "prod_NZKdYqrwEYx6iK",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

Update a price

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

Parameters

activeboolean
Whether the price can be used for new purchases. Defaults to true.

metadatadictionary
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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

nicknamestring
A brief description of the price, hidden from customers.

More parameters

currency_optionsdictionary

lookup_keystring

tax_behaviorenum

transfer_lookup_keyboolean

Returns

The updated price object is returned upon success. Otherwise, this call raises an error.

POST /v1/prices/:id

Server-side language

import stripe
stripe.api_key = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"
stripe.Price.modify(
  "price_1MoBy5LkdIwHu7ixZhnattbh",
  metadata={"order_id": "6735"},
)

Response

{
  "id": "price_1MoBy5LkdIwHu7ixZhnattbh",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1679431181,
  "currency": "usd",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {
    "order_id": "6735"
  },
  "nickname": null,
  "product": "prod_NZKdYqrwEYx6iK",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

Retrieve a price

Retrieves the price with the given ID.

Parameters

No parameters.

Returns

Returns a price if a valid price or plan ID was provided. Raises an error otherwise.

GET /v1/prices/:id

Server-side language

import stripe
stripe.api_key = "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc"
stripe.Price.retrieve("price_1MoBy5LkdIwHu7ixZhnattbh")

Response

{
  "id": "price_1MoBy5LkdIwHu7ixZhnattbh",
  "object": "price",
  "active": true,
  "billing_scheme": "per_unit",
  "created": 1679431181,
  "currency": "usd",
  "custom_unit_amount": null,
  "livemode": false,
  "lookup_key": null,
  "metadata": {},
  "nickname": null,
  "product": "prod_NZKdYqrwEYx6iK",
  "recurring": {
    "aggregate_usage": null,
    "interval": "month",
    "interval_count": 1,
    "trial_period_days": null,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": null,
  "transform_quantity": null,
  "type": "recurring",
  "unit_amount": 1000,
  "unit_amount_decimal": "1000"
}

Prices

The Price object

Attributes

idstring

activeboolean

currencyenum

metadatadictionary

nicknamenullable string

productstringExpandable

recurringnullable dictionary

typeenum

unit_amountnullable integer

More attributesExpand all

objectstring

billing_schemeenum

createdtimestamp

currency_optionsnullable dictionaryExpandable

custom_unit_amountnullable dictionary

livemodeboolean

lookup_keynullable string

tax_behaviornullable enum

tiersnullable array of dictionariesExpandable

tiers_modenullable enum

transform_quantitynullable dictionary

unit_amount_decimalnullable decimal string

Create a price

Parameters

currencyenumRequired

activeboolean

metadatadictionary

nicknamestring

productstringRequired unless product_data is provided

recurringdictionary

unit_amountintegerRequired conditionally

More parametersExpand all

billing_schemeenum

currency_optionsdictionary

custom_unit_amountdictionaryRequired unless unit_amount is provided

lookup_keystring

product_datadictionaryRequired unless product is provided

tax_behaviorenum

tiersarray of dictionariesRequired if billing_scheme=tiered

tiers_modeenumRequired if billing_scheme=tiered

transfer_lookup_keyboolean

transform_quantitydictionary

unit_amount_decimalstring

Returns

Update a price

Parameters

activeboolean

metadatadictionary

nicknamestring

More parametersExpand all

currency_optionsdictionary

lookup_keystring

tax_behaviorenum

transfer_lookup_keyboolean

Returns

Retrieve a price

Parameters

Returns

More attributes

More parameters

More parameters