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
    }
  ]
}

Delete a rate card rate v2

Remove an existing Rate from a RateCard. This will create a new RateCard version without that rate.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the rate to remove.

rate_card_idstringRequired
The ID of the RateCard.

Returns

Response attributes

idstring
The ID of the rate that was removed.

objectstring
String representing the object’s type. Objects of the same type share the same value.

Error Codes

400rate_card_inactive_error

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

400rate_card_rate_delete_inactive

Returned when a user tries to remove a rate that is not available in the latest rate card version.

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

404rate_card_rate_not_found

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

DELETE /v2/billing/rate_cards/:id/rates/:id

cURL

curl -X DELETE 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"
}

RateCardRate event types v2

This is a list of all public thin events we currently send for updates to RateCardRate, which are continually evolving and expanding. The payload of thin events is unversioned. During processing, you must fetch the versioned event from the API or fetch the resource’s current state.

Event types

Type

Filter events by type

Type

v2.billing.rate_card_rate.created

Occurs when a RateCardRate is created.

Attributes

idstring
Unique identifier for the event.

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

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which 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.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring, value is "v2.billing.rate_card_rate.created"
The type of the event.

Fetched attributes

dataobject
Additional data about the event.

Event payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SKjChAbYmk9HWJNpV16RuKJoESSQUtPVJKIgeI4D25PM",
  "object": "v2.core.event",
  "type": "v2.billing.rate_card_rate.created",
  "livemode": true,
  "related_object": {
    "id": "rcdr_61SKjCgnGytNLE2Rk16RuKJoESSQUtPVJKIgeI4D2B9s",
    "type": "v2.billing.rate_card_rate",
    "url": "/v2/billing/rate_cards/:rate_card_id/rates/rcdr_61SKjCgnGytNLE2Rk16RuKJoESSQUtPVJKIgeI4D2B9s"
  }
}

Event handler

Server-side language

# Select a client library to see examples of
# parsing and retrieving event details.

Fetched payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SKjChAbYmk9HWJNpV16RuKJoESSQUtPVJKIgeI4D25PM",
  "object": "v2.core.event",
  "type": "v2.billing.rate_card_rate.created",
  "livemode": true,
  "related_object": {
    "id": "rcdr_61SKjCgnGytNLE2Rk16RuKJoESSQUtPVJKIgeI4D2B9s",
    "type": "v2.billing.rate_card_rate",
    "url": "/v2/billing/rate_cards/:rate_card_id/rates/rcdr_61SKjCgnGytNLE2Rk16RuKJoESSQUtPVJKIgeI4D2B9s"
  },
  "data": {
    "billable_item": "bli_61SKiH6IK4ZFVDmkq16RuKJoESSQUtPVJKIgeI4D2JAm",
    "created": "2025-01-01T00:00:00.000Z",
    "rate_card": "rcd_61SKiGyy91q3JVsLw16RuKJoESSQUtPVJKIgeI4D2Omu",
    "rate_card_version": "rcdv_61SKjCgYDR2qkt8vg16RuKJoESSQUtPVJKIgeI4D2Pku"
  }
}

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

Delete a rate card rate v2

Parameters

idstringRequired

rate_card_idstringRequired

Returns

Response attributes

idstring

objectstring

RateCardRate event types v2

Event types

Attributes

idstring

objectstring, value is "v2.core.event"

contextnullable string

createdtimestamp

livemodeboolean

reasonnullable object

related_objectnullable object

typestring, value is "v2.billing.rate_card_rate.created"

Fetched attributes

dataobject