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
Privacy
Webhooks

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.

  • 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 associative arrayExpandable

  • custom_unit_amountnullable associative array

  • livemodeboolean

  • lookup_keynullable string

  • 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": {
    "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.

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

  • custom_unit_amountassociative arrayRequired unless unit_amount is provided

  • lookup_keystring

  • product_dataassociative arrayRequired unless product is provided

  • 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
$stripe = new \Stripe\StripeClient('sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$price = $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": {
    "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.

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

  • lookup_keystring

  • transfer_lookup_keyboolean

Returns

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

POST /v1/prices/:id
$stripe = new \Stripe\StripeClient('sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$price = $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": {
    "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
$stripe = new \Stripe\StripeClient('sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$price = $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": {
    "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"
}

List all prices 

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 or one_time.

    Possible enum values
    one_time
    recurring

More parameters

  • createdassociative array

  • ending_beforestring

  • limitinteger

  • lookup_keysarray of strings

  • recurringassociative array

  • starting_afterstring

Returns

A associative array with a data property that contains an array of up to limit prices, starting after prices starting_after. Each entry in the array is a separate price object. If no more prices are available, the resulting array will be empty.

GET /v1/prices
$stripe = new \Stripe\StripeClient('sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2');
$prices = $stripe->prices->all(['limit' => 3]);
Response
{
  "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": {
        "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"
    }
  ]
}