Retrieve a rate card rate v2

Retrieve a Rate object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the rate to retrieve.

rate_card_idstringRequired
The ID of the RateCard.

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

404rate_card_rate_not_found

Returned when the provided rate card rate ID cannot be found.

GET /v2/billing/rate_cards/:id/rates/:id

Server-side language

curl https://api.stripe.com/v2/billing/rate_cards/rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG/rates/rcdr_test_61Rc0EwMrmxaJaSum16RM8VQESSQ4t1K5KYFAmKUSPLs \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

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
}

Retrieve a rate card version v2

Retrieve a specific version of a RateCard object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the version to retrieve.

rate_card_idstringRequired
The ID of the RateCard object.

Returns

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

Error Codes

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

404rate_card_version_not_found

Returned when the provided rate_card_version ID cannot be found.

GET /v2/billing/rate_cards/:id/versions/:id

Server-side language

curl https://api.stripe.com/v2/billing/rate_cards/rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG/versions/rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

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

List rate card rates v2

List all Rates associated with a RateCard for a specific version (defaults to latest). Rates remain active for all subsequent versions until a new Rate is created for the same MeteredItem.

Learn more about calling API v2 endpoints.

Parameters

rate_card_idstringRequired
The ID of the RateCard to retrieve rates for.

limitinteger
Optionally set the maximum number of results per page. Defaults to 20.

metered_itemstring
Optionally filter by a MeteredItem.

pagestring
Opaque page token.

rate_card_versionstring
Optionally filter by a RateCard version. If not specified, defaults to the latest version.

Returns

Response attributes

dataarray of objects
The retrieved RateCard rates.

next_page_urlnullable string
The URL of the next page of results, if there is one.

previous_page_urlnullable string
The URL of the previous page of results, if there is one.

GET /v2/billing/rate_cards/:id/rates

Server-side language

curl 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"

Response

{
  "data": [
    {
      "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
    }
  ]
}

List rate cards v2

List all RateCard objects.

Learn more about calling API v2 endpoints.

Parameters

activeboolean
Optionally filter to active/inactive RateCards.

limitinteger
Optionally set the maximum number of results per page. Defaults to 20.

pagestring
Opaque page token.

Returns

Response attributes

dataarray of objects
The retrieved RateCards.

next_page_urlnullable string
The URL of the next page of results, if there is one.

previous_page_urlnullable string
The URL of the previous page of results, if there is one.

GET /v2/billing/rate_cards

cURL

curl https://api.stripe.com/v2/billing/rate_cards \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

{
  "data": [
    {
      "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
    }
  ]
}

List rate card versions v2

List the versions of a RateCard object. Results are sorted in reverse chronological order (most recent first).

Learn more about calling API v2 endpoints.

Parameters

rate_card_idstringRequired
The ID of the RateCard to retrieve versions for.

limitinteger
Optionally set the maximum number of results per page. Defaults to 20.

pagestring
Opaque page token.

Returns

Response attributes

dataarray of objects
The retrieved RateCard versions.

next_page_urlnullable string
The URL of the next page of results, if there is one.

previous_page_urlnullable string
The URL of the previous page of results, if there is one.

Error Codes

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

GET /v2/billing/rate_cards/:id/versions

Server-side language

curl https://api.stripe.com/v2/billing/rate_cards/rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG/versions \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

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

Retrieve a rate card rate v2

Parameters

idstringRequired

rate_card_idstringRequired

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

Retrieve a rate card version v2

Parameters

idstringRequired

rate_card_idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.rate_card_version"

createdtimestamp

livemodeboolean

rate_card_idstring

List rate card rates v2

Parameters

rate_card_idstringRequired

limitinteger

metered_itemstring

pagestring

rate_card_versionstring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

List rate cards v2

Parameters

activeboolean

limitinteger

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

List rate card versions v2

Parameters

rate_card_idstringRequired

limitinteger

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string