The RateCard object

Attributes

idstring
The ID of the RateCard.

objectstring, value is "v2.billing.rate_card"
String representing the object’s type. Objects of the same type share the same value of the object field.

activeboolean
Whether this RateCard is active. Inactive RateCards cannot be used in new activations or have new rates added.

createdtimestamp
Timestamp of when the object was created.

currencystring
The currency of this RateCard.

display_namestring
A customer-facing name for the RateCard. This name is used in Stripe-hosted products like the Customer Portal and Checkout. It does not show up on Invoices. Maximum length of 250 characters.

latest_versionstring
The ID of this RateCard’s most recently created version.

live_versionstring
The ID of the version that will be used by all Subscriptions when no specific version is specified.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

service_intervalenum
The interval for assessing service. For example, a monthly RateCard with a rate of $1 for the first 10 “workloads” and $2 thereafter means “$1 per workload up to 10 workloads during a month of service.” This is similar to but distinct from billing interval; the service interval deals with the rate at which the customer accumulates fees, while the billing interval in Cadence deals with the rate the customer is billed.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service. For example, set this to 3 and service_interval to "month" in order to specify quarterly service.

tax_behaviorenum
The Stripe Tax tax behavior - whether the rates are inclusive or exclusive of tax.
Possible enum values
exclusive
Price excludes tax.
inclusive
Price includes tax.

The RateCard object

{
  "id": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "object": "v2.billing.rate_card",
  "active": true,
  "currency": "usd",
  "display_name": "My Rate Card",
  "latest_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "live_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "metadata": {},
  "service_interval": "month",
  "service_interval_count": 2,
  "tax_behavior": "exclusive",
  "created": "2024-11-26T16:33:03.000Z"
}

The RateCardVersion object

Attributes

idstring
The ID of the RateCardVersion.

objectstring, value is "v2.billing.rate_card_version"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

rate_card_idstring
The ID of the RateCard that this version belongs to.

The RateCardVersion object

{
  "id": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "object": "v2.billing.rate_card.version",
  "rate_card_id": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "created": "2024-11-26T16:33:03.000Z"
}

Create a rate card v2

Create a RateCard object.

Learn more about calling API v2 endpoints.

Parameters

currencystringRequired
The currency of this RateCard.

display_namestringRequired
A customer-facing name for the RateCard. This name is used in Stripe-hosted products like the Customer Portal and Checkout. It does not show up on Invoices. Maximum length of 250 characters.

service_intervalenumRequired
The interval for assessing service. For example, a monthly RateCard with a rate of $1 for the first 10 “workloads” and $2 thereafter means “$1 per workload up to 10 workloads during a month of service.” This is similar to but distinct from billing interval; the service interval deals with the rate at which the customer accumulates fees, while the billing interval in Cadence deals with the rate the customer is billed.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countintegerRequired
The length of the interval for assessing service. For example, set this to 3 and service_interval to "month" in order to specify quarterly service.

tax_behaviorenumRequired
The Stripe Tax tax behavior - whether the rates are inclusive or exclusive of tax.
Possible enum values
exclusive
Price excludes tax.
inclusive
Price includes tax.

metadatamap
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.

Returns

Response attributes

idstring
The ID of the RateCard.

objectstring, value is "v2.billing.rate_card"
String representing the object’s type. Objects of the same type share the same value of the object field.

activeboolean
Whether this RateCard is active. Inactive RateCards cannot be used in new activations or have new rates added.

createdtimestamp
Timestamp of when the object was created.

currencystring
The currency of this RateCard.

display_namestring
A customer-facing name for the RateCard. This name is used in Stripe-hosted products like the Customer Portal and Checkout. It does not show up on Invoices. Maximum length of 250 characters.

latest_versionstring
The ID of this RateCard’s most recently created version.

live_versionstring
The ID of the version that will be used by all Subscriptions when no specific version is specified.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

service_intervalenum
The interval for assessing service. For example, a monthly RateCard with a rate of $1 for the first 10 “workloads” and $2 thereafter means “$1 per workload up to 10 workloads during a month of service.” This is similar to but distinct from billing interval; the service interval deals with the rate at which the customer accumulates fees, while the billing interval in Cadence deals with the rate the customer is billed.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service. For example, set this to 3 and service_interval to "month" in order to specify quarterly service.

tax_behaviorenum
The Stripe Tax tax behavior - whether the rates are inclusive or exclusive of tax.
Possible enum values
exclusive
Price excludes tax.
inclusive
Price includes tax.

Error Codes

400product_catalog_unsupported_currency

Returned when the currency provided is not a valid currency.

POST /v2/billing/rate_cards

cURL

curl -X POST https://api.stripe.com/v2/billing/rate_cards \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "display_name": "My Rate Card",
    "service_interval": "month",
    "service_interval_count": 1,
    "currency": "usd",
    "tax_behavior": "exclusive"
  }'

Response

{
  "id": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "object": "v2.billing.rate_card",
  "active": true,
  "currency": "usd",
  "display_name": "My Rate Card",
  "latest_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "live_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "metadata": {},
  "service_interval": "month",
  "service_interval_count": 2,
  "tax_behavior": "exclusive",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}

Create a rate card rate v2

Set the rate for a MeteredItem on the latest version of a RateCard object. This will create a new RateCard version if the MeteredItem already has a rate on the RateCard.

Learn more about calling API v2 endpoints.

Parameters

rate_card_idstringRequired
The ID of the RateCard to create a new rate for.

custom_pricing_unit_amountobjectPreview feature
The custom pricing unit that this rate binds to.

metadatamap
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.

metered_itemstring
The MeteredItem that this rate binds to.

pricestring
The ID of the Price object to take price information from. The Price must have the same interval as the RateCard. Updates to the Price will not be reflected in the RateCard or its rates.

tiering_modeenum

Defines whether the tiered price should be graduated or volume-based. In volume-based tiering, the maximum quantity within a period determines the per-unit price. In graduated tiering, the pricing changes as the quantity grows into new tiers. Can only be set if tiers is set.

Possible enum values

graduated

Use graduated tiering: the pricing at each tier applies to the quantity within that tier.

volume

Use volume-based tiering: the maximum quantity within a period determines the per-unit price for that period.

tiersarray of objects
Each element represents a pricing tier. Cannot be set if unit_amount is provided.

transform_quantityobject
Apply a transformation to the reported usage or set quantity before computing the amount billed.

unit_amountstring
The per-unit amount to be charged, represented as a decimal string in minor currency units with at most 12 decimal places. Cannot be set if tiers is provided.

Returns

Response attributes

idstring
The ID of the RateCardRate.

objectstring, value is "v2.billing.rate_card_rate"
String representing the object’s type. Objects of the same type share the same value of the object field.

createdtimestamp
Timestamp of when the object was created.

custom_pricing_unit_amountnullable objectPreview feature
The custom pricing unit that this rate binds to.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

metered_itemobject
The MeteredItem that this rate binds to.

rate_cardstring
The ID of the RateCard it belongs to.

rate_card_versionstring
The ID of the RateCard version it was created on.

tiering_modenullable enum

Defines whether the tiering price should be graduated or volume-based. In volume-based tiering, the maximum quantity within a period determines the per-unit price. In graduated tiering, the pricing changes as the quantity grows into new tiers. Can only be set if tiers is set.

Possible enum values

graduated

Use graduated tiering: the pricing at each tier applies to the quantity within that tier.

volume

Use volume-based tiering: the maximum quantity within a period determines the per-unit price for that period.

tiersarray of objects
Each element represents a pricing tier. Cannot be set if unit_amount is provided.

transform_quantitynullable object
Apply a transformation to the reported usage or set quantity before computing the amount billed.

unit_amountnullable string
The per-unit amount to be charged, represented as a decimal string in minor currency units with at most 12 decimal places. Cannot be set if tiers is provided.

Error Codes

400display_name_too_long

Returned when the provided display_name is longer than the maximum length of 100 characters.

400price_mismatch_with_rate_card

Returned when the price has fields that don’t match those on the rate card. The price must have the same currency as the rate card, and its recurring.interval and recurring.interval_count must be the same as the rate card’s service_interval and service_interval_count.

400product_catalog_unsupported_currency

Returned when the currency provided is not a valid currency.

400product_pricing_already_exists

Returned when a product has multiple prices on a rate card.

400rate_card_inactive_error

Returned when a user tries to modify a rate or subscription for an inactive rate card.

400rate_card_price_already_exists

Returned when the price already exists on a rate card.

400rate_card_price_meter_exists

Returned when a new price is set which has a different meter from the original meter set.

400rate_card_price_not_recurring

Returned when the price is not recurring.

400usage_type_without_meter

Returned when the type=usage and no meter is provided.

404custom_pricing_unit_not_found

Returned by CustomPricingUnit API when the custom pricing unit is not found.

404meter_not_found

Returned when the provided meter ID cannot be found.

404metered_item_not_found

Returned when the provided metered_item ID cannot be found.

404price_not_found

Returned when the provided price ID cannot be found.

404product_not_found

Returned when the provided product ID cannot be found.

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

POST /v2/billing/rate_cards/:id/rates

Server-side language

curl -X POST https://api.stripe.com/v2/billing/rate_cards/rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG/rates \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json {"price":"price_1QRybyH5wvQ9UC0Vsrt78m5V"}

Response

{
  "id": "rcdr_test_61Rc0EwMrmxaJaSum16RM8VQESSQ4t1K5KYFAmKUSPLs",
  "object": "v2.billing.rate_card.rate",
  "metered_item": {
    "id": "blbli_test_61Rc0Ew1oiQyokWns16RM8VQESSQ4t1K5KYFAmKUSA5o",
    "object": "v2.billing.metered_item",
    "display_name": "API requests",
    "lookup_key": "api_requests",
    "unit_label": "Price per 100 requests",
    "meter": "mtr_test_61RCjiqdTDC91zgip41IqPCzPnxqqSVc",
    "created": "2024-11-26T16:33:03.000Z",
    "livemode": false
  },
  "metadata": {},
  "rate_card": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "rate_card_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "tiers": [],
  "unit_amount": "1000.0",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": false
}

Update a rate card v2

Update a RateCard object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the RateCard to update.

activeboolean
Sets whether the RateCard is active. Inactive RateCards cannot be used in new activations or have new rates added.

display_namestring
A customer-facing name for the RateCard. This name is used in Stripe-hosted products like the Customer Portal and Checkout. It does not show up on Invoices. Maximum length of 250 characters.

live_versionstring
Changes the version that new RateCard activations will use. Providing live_version = "latest" will set the RateCard’s live_version to its latest version.

metadatamap
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.

Returns

Response attributes

idstring
The ID of the RateCard.

objectstring, value is "v2.billing.rate_card"
String representing the object’s type. Objects of the same type share the same value of the object field.

activeboolean
Whether this RateCard is active. Inactive RateCards cannot be used in new activations or have new rates added.

createdtimestamp
Timestamp of when the object was created.

currencystring
The currency of this RateCard.

display_namestring
A customer-facing name for the RateCard. This name is used in Stripe-hosted products like the Customer Portal and Checkout. It does not show up on Invoices. Maximum length of 250 characters.

latest_versionstring
The ID of this RateCard’s most recently created version.

live_versionstring
The ID of the version that will be used by all Subscriptions when no specific version is specified.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable 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.

service_intervalenum
The interval for assessing service. For example, a monthly RateCard with a rate of $1 for the first 10 “workloads” and $2 thereafter means “$1 per workload up to 10 workloads during a month of service.” This is similar to but distinct from billing interval; the service interval deals with the rate at which the customer accumulates fees, while the billing interval in Cadence deals with the rate the customer is billed.
Possible enum values
day
Assess service by days.
month
Assess service by months.
week
Assess service by weeks.
year
Assess service by years.

service_interval_countinteger
The length of the interval for assessing service. For example, set this to 3 and service_interval to "month" in order to specify quarterly service.

tax_behaviorenum
The Stripe Tax tax behavior - whether the rates are inclusive or exclusive of tax.
Possible enum values
exclusive
Price excludes tax.
inclusive
Price includes tax.

Error Codes

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

POST /v2/billing/rate_cards/:id

cURL

curl -X POST https://api.stripe.com/v2/billing/rate_cards/rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "display_name": "My Rate Card with a new default live version",
    "live_version": "rcdv_test_72c0EnbIs6eHM8VQESSQ4t1K5KYFAmKAB1Ab"
  }'

Response

{
  "id": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "object": "v2.billing.rate_card",
  "active": true,
  "currency": "usd",
  "display_name": "My Rate Card with a new default live version",
  "latest_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "live_version": "rcdv_test_72c0EnbIs6eHM8VQESSQ4t1K5KYFAmKAB1Ab",
  "metadata": {},
  "service_interval": "month",
  "service_interval_count": 2,
  "tax_behavior": "exclusive",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}

The RateCard object

Attributes

idstring

objectstring, value is "v2.billing.rate_card"

activeboolean

createdtimestamp

currencystring

display_namestring

latest_versionstring

live_versionstring

livemodeboolean

metadatanullable map

service_intervalenum

service_interval_countinteger

tax_behaviorenum

The RateCardVersion object

Attributes

idstring

objectstring, value is "v2.billing.rate_card_version"

createdtimestamp

livemodeboolean

rate_card_idstring

Create a rate card v2

Parameters

currencystringRequired

display_namestringRequired

service_intervalenumRequired

service_interval_countintegerRequired

tax_behaviorenumRequired

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.rate_card"

activeboolean

createdtimestamp

currencystring

display_namestring

latest_versionstring

live_versionstring

livemodeboolean

metadatanullable map

service_intervalenum

service_interval_countinteger

tax_behaviorenum

Create a rate card rate v2

Parameters

rate_card_idstringRequired

custom_pricing_unit_amountobjectPreview feature

metadatamap

metered_itemstring

pricestring

tiering_modeenum

tiersarray of objects

transform_quantityobject

unit_amountstring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.rate_card_rate"

createdtimestamp

custom_pricing_unit_amountnullable objectPreview feature

livemodeboolean

metadatanullable map

metered_itemobject

rate_cardstring

rate_card_versionstring

tiering_modenullable enum

tiersarray of objects

transform_quantitynullable object

unit_amountnullable string

Update a rate card v2

Parameters

idstringRequired

activeboolean

display_namestring

live_versionstring

metadatamap

Returns

Response attributes