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
andusage_
.type - typeenum
One of
one_
odertime recurring
depending on whether the price is for a one-time purchase or a recurring (subscription) purchase.Possible enum valuesone_
time recurring
- unit_
amount nullable integerThe 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_
scheme enum - createdtimestamp
- currency_
options nullable objectExpandable - custom_
unit_ nullable objectamount - livemodeboolean
- lookup_
key nullable string - tax_
behavior nullable enum - tiersnullable array of objectsExpandable
- tiers_
mode nullable enum - transform_
quantity nullable object - unit_
amount_ nullable decimal stringdecimal
{ "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"}
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
andusage_
.type - unit_
amount integerRequired conditionallyA positive integer in cents (or 0 for a free price) representing how much to charge. One of
unit_
,amount unit_
, oramount_ decimal custom_
is required, unlessunit_ amount billing_
.scheme=tiered
More parameters
- billing_
scheme enum - currency_
options object - custom_
unit_ objectRequired unless unit_amount is providedamount - lookup_
key string - product_
data objectRequired unless product is provided - tax_
behavior enum - tiersarray of objectsRequired if billing_scheme=tiered
- tiers_
mode enumRequired if billing_scheme=tiered - transfer_
lookup_ booleankey - transform_
quantity object - unit_
amount_ stringdecimal
Returns
The newly created Price
object is returned upon success. Otherwise, this call raises an error.
{ "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"}
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_
options object - lookup_
key string - tax_
behavior enum - transfer_
lookup_ booleankey
Returns
The updated price object is returned upon success. Otherwise, this call raises an error.
{ "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"}
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.
{ "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"}
Returns a list of your active prices, excluding inline prices. For the list of inactive prices, set active
to false.
Parameters
- activeboolean
Only return prices that are active or inactive (e.g., pass
false
to list all inactive prices). - currencyenum
Only return prices for the given currency.
- productstring
Only return prices for the given product.
- typeenum
Only return prices of type
recurring
oderone_
.time Possible enum valuesone_
time recurring
More parameters
- createdobject
- ending_
before string - limitinteger
- lookup_
keys array of strings - recurringobject
- starting_
after string
Returns
A dictionary with a data
property that contains an array of up to limit
prices, starting after prices starting_
. Each entry in the array is a separate price object. If no more prices are available, the resulting array will be empty.
{ "object": "list", "url": "/v1/prices", "has_more": false, "data": [ { "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" } {...} {...} ],}