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.

metadataassociative array
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 associative array
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 associative arrayExpandable

custom_unit_amountnullable associative array

livemodeboolean

lookup_keynullable string

tax_behaviornullable enum

tiersnullable array of associative arraysExpandable

tiers_modenullable enum

transform_quantitynullable associative array

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.

metadataassociative array
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.

recurringassociative array
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, unit_amount_decimal, or custom_unit_amount is required, unless billing_scheme=tiered.

More parameters

billing_schemeenum

currency_optionsassociative array

custom_unit_amountassociative arrayRequired unless unit_amount is provided

lookup_keystring

product_dataassociative arrayRequired unless product is provided

tax_behaviorenum

tiersarray of associative arraysRequired if billing_scheme=tiered

tiers_modeenumRequired if billing_scheme=tiered

transfer_lookup_keyboolean

transform_quantityassociative array

unit_amount_decimalstring

Returns

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

POST /v1/prices

Server-side language

$stripe = new \Stripe\StripeClient('sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc');
$stripe->prices->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.

metadataassociative array
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_optionsassociative array

lookup_keystring

tax_behaviorenum

transfer_lookup_keyboolean

Returns

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

POST /v1/prices/:id

Server-side language

$stripe = new \Stripe\StripeClient('sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc');
$stripe->prices->update(
  '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. Throws an error otherwise.

GET /v1/prices/:id

Server-side language

$stripe = new \Stripe\StripeClient('sk_test_4eC39Hq...arjtT1zdp7dcsk_test_4eC39HqLyjWDarjtT1zdp7dc');
$stripe->prices->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

metadataassociative array

nicknamenullable string

productstringExpandable

recurringnullable associative array

typeenum

unit_amountnullable integer

More attributesExpand all

objectstring

billing_schemeenum

createdtimestamp

currency_optionsnullable associative arrayExpandable

custom_unit_amountnullable associative array

livemodeboolean

lookup_keynullable string

tax_behaviornullable enum

tiersnullable array of associative arraysExpandable

tiers_modenullable enum

transform_quantitynullable associative array

unit_amount_decimalnullable decimal string

Create a price

Parameters

currencyenumRequired

activeboolean

metadataassociative array

nicknamestring

productstringRequired unless product_data is provided

recurringassociative array

unit_amountintegerRequired conditionally

More parametersExpand all

billing_schemeenum

currency_optionsassociative array

custom_unit_amountassociative arrayRequired unless unit_amount is provided

lookup_keystring

product_dataassociative arrayRequired unless product is provided

tax_behaviorenum

tiersarray of associative arraysRequired if billing_scheme=tiered

tiers_modeenumRequired if billing_scheme=tiered

transfer_lookup_keyboolean

transform_quantityassociative array

unit_amount_decimalstring

Returns

Update a price

Parameters

activeboolean

metadataassociative array

nicknamestring

More parametersExpand all

currency_optionsassociative array

lookup_keystring

tax_behaviorenum

transfer_lookup_keyboolean

Returns

Retrieve a price

Parameters

Returns

More attributes

More parameters

More parameters