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.

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.

  • metadataobject

    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 object

    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 objectExpandable

  • custom_unit_amountnullable object

  • livemodeboolean

  • lookup_keynullable string

  • tax_behaviornullable enum

  • tiersnullable array of objectsExpandable

  • tiers_modenullable enum

  • transform_quantitynullable object

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

  • metadataobject

    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.

  • recurringobject

    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_optionsobject

  • custom_unit_amountobjectRequired unless unit_amount is provided

  • lookup_keystring

  • product_dataobjectRequired unless product is provided

  • tax_behaviorenum

  • tiersarray of objectsRequired if billing_scheme=tiered

  • tiers_modeenumRequired if billing_scheme=tiered

  • transfer_lookup_keyboolean

  • transform_quantityobject

  • unit_amount_decimalstring

Returns

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

POST /v1/prices
curl https://api.stripe.com/v1/prices \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
-d currency=usd \
-d unit_amount=1000 \
-d "recurring[interval]"=month \
-d "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.

  • metadataobject

    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_optionsobject

  • 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
curl https://api.stripe.com/v1/prices/price_1MoBy5LkdIwHu7ixZhnattbh \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:" \
-d "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
curl https://api.stripe.com/v1/prices/price_1MoBy5LkdIwHu7ixZhnattbh \
-u "sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc:"
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"
}
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g., )
The Stripe Shell is best experienced on desktop.
$