Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

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.

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

  • tax_behaviornullable enum

    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.

    Possible enum values
    exclusive
    inclusive
    unspecified

  • 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

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

  • tax_behaviorenumRecommended if calculating taxes

    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.

    Possible enum values
    exclusive
    inclusive
    unspecified

  • unit_amountintegerRequired conditionally

    A positive integer in cents (or 0 for a free price) representing how much to charge. One of unit_amount, unit_amount_decimal, 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

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

  • tax_behaviorenumRecommended if calculating taxes

    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.

    Possible enum values
    exclusive
    inclusive
    unspecified

More parameters

  • currency_optionsobject

  • lookup_keystring

  • 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"
}