Create a price
POST / v1 / prices
Creates a new Price for an existing Product. The Price can be recurring or one-time.
Parameters
- currency enum Required Three-letter ISO currency code, in lowercase. Must be a supported currency.
- active boolean Whether the price can be used for new purchases. Defaults to
true. - metadata map 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. - nickname string A brief description of the price, hidden from customers.
- product string Required unless product_data is provided The ID of the Product that this Price will belong to.
- recurring object The recurring components of a price such as
intervalandusage_type. - tax _ behavior enum Recommended 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, orunspecified. Once specified as eitherinclusiveorexclusive, it cannot be changed. Possible enum valuesexclusiveinclusiveunspecified - unit _ amount integer Required conditionally A positive integer in the smallest currency unit (or 0 for a free price) representing how much to charge. One of
unit_amount,unit_amount_decimal, orcustom_unit_amountis required, unlessbilling_scheme=tiered.
More parameters
- billing _ scheme enum
- currency _ options map
- custom _ unit _ amount object Required unless unit_amount is provided
- lookup _ key string
- product _ data object Required unless product is provided
- tiers array of objects Required if billing_scheme=tiered
- tiers _ mode enum Required if billing_scheme=tiered
- transfer _ lookup _ key boolean
- transform _ quantity object
- unit _ amount _ decimal string
Returns
The newly created Price object is returned upon success. Otherwise, this call raises an error.
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": { "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
POST / v1 / prices /:id
Updates the specified price by setting the values of the parameters passed. Any parameters not provided are left unchanged.
Parameters
- active boolean Whether the price can be used for new purchases. Defaults to
true. - metadata map 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. - nickname string A brief description of the price, hidden from customers.
- tax _ behavior enum Recommended 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, orunspecified. Once specified as eitherinclusiveorexclusive, it cannot be changed. Possible enum valuesexclusiveinclusiveunspecified
More parameters
- currency _ options map
- lookup _ key string
- transfer _ lookup _ key boolean
Returns
The updated price object is returned upon success. Otherwise, this call raises an error.
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": { "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
GET / v1 / prices /:id
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.
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": { "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"}