Skip to main content
POST
/
v1
/
prices
Create a Price
curl --request POST \
  --url https://api.leanrails.com/v1/prices \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "product": "<string>",
  "currency": "<string>",
  "unit_amount": 1,
  "unit_amount_decimal": "<string>",
  "custom_unit_amount": {
    "enabled": true,
    "minimum": 1,
    "maximum": 2,
    "preset": 1
  },
  "active": true,
  "type": "one_time",
  "billing_scheme": "per_unit",
  "recurring": {
    "interval": "day",
    "interval_count": 183,
    "usage_type": "licensed"
  },
  "tax_behavior": "unspecified",
  "tiers_mode": "graduated",
  "tiers": [
    {
      "up_to": 123,
      "flat_amount": 123,
      "flat_amount_decimal": "<string>",
      "unit_amount": 123,
      "unit_amount_decimal": "<string>"
    }
  ],
  "transform_quantity": {
    "divide_by": 2,
    "round": "up"
  },
  "lookup_key": "<string>",
  "transfer_lookup_key": true,
  "nickname": "<string>",
  "metadata": {}
}
'
{
  "id": "price_xxx",
  "object": "price",
  "active": true,
  "product": "prod_xxx",
  "currency": "usd",
  "type": "one_time",
  "billing_scheme": "per_unit",
  "tax_behavior": "inclusive",
  "metadata": {},
  "livemode": false,
  "created": 1234567890,
  "unit_amount": 2000,
  "unit_amount_decimal": "<string>",
  "custom_unit_amount": {
    "enabled": true,
    "minimum": 1,
    "maximum": 2,
    "preset": 1
  },
  "recurring": {
    "interval": "day",
    "interval_count": 183,
    "usage_type": "licensed"
  },
  "tiers_mode": "graduated",
  "tiers": [
    {
      "up_to": 123,
      "flat_amount": 123,
      "flat_amount_decimal": "<string>",
      "unit_amount": 123,
      "unit_amount_decimal": "<string>"
    }
  ],
  "transform_quantity": {
    "divide_by": 2,
    "round": "up"
  },
  "lookup_key": "<string>",
  "nickname": "<string>"
}

Authorizations

​
Authorization
string
header
required

Use your secret API key as the username with an empty password.

Headers

​
Idempotency-Key
string
required

Unique key to ensure idempotent requests.

Maximum string length: 255
​
X-API-Version
string

Override the API version for this request.

Body

application/json
​
product
string
required

The ID of the product this price belongs to.

Pattern: ^prod_
​
currency
string
required

Three-letter ISO currency code.

Required string length: 3
​
unit_amount
integer

Amount in smallest currency unit. Required for per_unit billing unless custom_unit_amount is provided.

Required range: x >= 0
​
unit_amount_decimal
string

Amount in smallest currency unit as a decimal string for high-precision.

​
custom_unit_amount
object
​
active
boolean
default:true

Whether the price is currently active.

​
type
enum<string>
default:one_time

Whether the price is for a one-time purchase or a recurring subscription.

Available options:
one_time,
recurring
​
billing_scheme
enum<string>
default:per_unit

Describes how to compute the price per period.

Available options:
per_unit,
tiered
​
recurring
object

Recurring billing details. Required when type is recurring.

​
tax_behavior
enum<string>
default:unspecified

Whether the price is tax-inclusive or tax-exclusive.

Available options:
inclusive,
exclusive,
unspecified
​
tiers_mode
enum<string>

Defines how tiers are applied. Required when billing_scheme is tiered.

Available options:
graduated,
volume
​
tiers
object[]

Pricing tiers. Required when billing_scheme is tiered.

​
transform_quantity
object
​
lookup_key
string

A lookup key to quickly find this price.

Maximum string length: 200
​
transfer_lookup_key
boolean

If true, any existing price with the same lookup_key will have its key unset.

​
nickname
string

A brief human-readable label for the price.

​
metadata
object

Set of key-value pairs for storing additional information.

Response

The created Price.

​
id
string
required
Example:

"price_xxx"

​
object
enum<string>
required
Available options:
price
​
active
boolean
required

Whether the price is currently active.

​
product
string
required

The ID of the product this price belongs to, or the expanded Product object.

Example:

"prod_xxx"

​
currency
string
required

Three-letter ISO currency code.

Example:

"usd"

​
type
enum<string>
required

Whether the price is for a one-time purchase or a recurring subscription.

Available options:
one_time,
recurring
​
billing_scheme
enum<string>
required

Describes how to compute the price per period.

Available options:
per_unit,
tiered
​
tax_behavior
enum<string>
required

Whether the price is tax-inclusive or tax-exclusive.

Available options:
inclusive,
exclusive,
unspecified
​
metadata
object
required

Set of key-value pairs for storing additional information.

​
livemode
boolean
required
Example:

false

​
created
integer
required

Unix timestamp.

Example:

1234567890

​
unit_amount
integer | null

Amount in smallest currency unit (e.g. cents).

Example:

2000

​
unit_amount_decimal
string | null

Amount in smallest currency unit as a decimal string.

​
custom_unit_amount
object

Settings for customer-specified amounts.

​
recurring
object

Recurring billing details. Present when type is recurring.

​
tiers_mode
enum<string> | null

How tiers are applied. Present when billing_scheme is tiered.

Available options:
graduated,
volume
​
tiers
object[] | null

Pricing tiers. Present when billing_scheme is tiered.

​
transform_quantity
object

Apply a transformation to the reported usage or set quantity.

​
lookup_key
string | null

A lookup key to quickly find this price (max 200 characters).

​
nickname
string | null

A brief human-readable label for the price.