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

Create a rate card subscription v2

Create a RateCardSubscription to bill a RateCard on a specified billing Cadence.

Learn more about calling API v2 endpoints.

Parameters

  • billing_cadencestringRequired

    The ID of the billing Cadence.

  • rate_cardstringRequired

    The ID of the RateCard.

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

  • rate_card_versionstring

    The ID of the RateCardVersion. If not specified, defaults to the “live_version” of the RateCard at the time of creation.

Returns

Response attributes

  • idstring

    The ID of the RateCardSubscription.

  • objectstring, value is "v2.billing.rate_card_subscription"

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

  • billing_cadencestring

    The ID of the billing Cadence.

  • collection_statusnullable enum

    The payment status of a RateCardSubscription.

    Possible enum values
    awaiting_customer_action

    The subscription payment is pending and requires customer action.

    current

    The subscription is in good standing. All payments have been successfully processed.

    past_due

    The subscription is currently overdue for payment. We are actively attempting to process the payment.

    paused

    Payment collection for the subscription is temporarily paused. The subscription may be resumed in the future, but no payments are being processed at this time.

    unpaid

    All attempts to collect payment for the subscription have been unsuccessful, and the outstanding balance is marked as uncollectible.

  • collection_status_transitionsnullable object

    The collection status transitions of the RateCardSubscription.

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

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

  • rate_cardstring

    The ID of the RateCard.

  • rate_card_versionstring

    The ID of the RateCardVersion.

  • servicing_statusnullable enum

    The servicing status of a RateCardSubscription.

    Possible enum values
    active

    The provisionee of this subscription is receiving servicing.

    canceled

    Servicing for this subscription is canceled.

    paused

    The servicing for the provisionee of this subscription is paused.

    pending

    The subscription is pending a successful payment and is not being serviced yet.

  • servicing_status_transitionsnullable object

    The servicing status transitions of the RateCardSubscription.

  • test_clocknullable string

    The ID of the Test Clock, if any.

Error Codes
400billing_cadence_canceled

Returned when trying to cancel a billing cadence that has already been canceled.

400currency_mismatch

Returned when creating a rate card subscription for a billing cadence and the rate card currency does not match the billing cadence currency.

400manual_configuration_inactive

Returned when the ManualTaxConfiguration is inactive.

400rate_card_inactive_error

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

400rate_card_subscription_already_exists

Returned when a user tries to create a rate card subscription for a billing cadence that has already subscribed to the same rate card.

400servicing_interval_exceeds_billing_interval

Returned when the rate card servicing interval exceeds the billing cadence cycle length.

400too_many_active_rate_card_subscriptions

Returned when a user tries to create a rate card subscription for a billing cadence that has already reached the limit of active subscriptions.

400unpriced_rate_card

Returned when no rates can be found for the given rate card ID and version.

404customer_not_found

Returned when the customer for the provided ID cannot be found.

404manual_tax_configuration_not_found

Returned when no ManualTaxConfiguration object was found for the given ID.

404no_merchant_found_for_compartment

Returned when the merchant ID cannot be determined for this workspace.

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.

POST /v2/billing/rate_card_subscriptions
curl -X POST https://api.stripe.com/v2/billing/rate_card_subscriptions \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "billing_cadence": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
    "rate_card": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
    "rate_card_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk"
  }'
Response
{
  "id": "rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM",
  "object": "v2.billing.rate_card_subscription",
  "billing_cadence": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
  "metadata": {},
  "rate_card": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "rate_card_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "collection_status": "current",
  "servicing_status": "active",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}

Update a rate card subscription v2

Update fields on an existing, active RateCardSubscription.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the RateCardSubscription to update.

  • 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 RateCardSubscription.

  • objectstring, value is "v2.billing.rate_card_subscription"

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

  • billing_cadencestring

    The ID of the billing Cadence.

  • collection_statusnullable enum

    The payment status of a RateCardSubscription.

    Possible enum values
    awaiting_customer_action

    The subscription payment is pending and requires customer action.

    current

    The subscription is in good standing. All payments have been successfully processed.

    past_due

    The subscription is currently overdue for payment. We are actively attempting to process the payment.

    paused

    Payment collection for the subscription is temporarily paused. The subscription may be resumed in the future, but no payments are being processed at this time.

    unpaid

    All attempts to collect payment for the subscription have been unsuccessful, and the outstanding balance is marked as uncollectible.

  • collection_status_transitionsnullable object

    The collection status transitions of the RateCardSubscription.

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

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

  • rate_cardstring

    The ID of the RateCard.

  • rate_card_versionstring

    The ID of the RateCardVersion.

  • servicing_statusnullable enum

    The servicing status of a RateCardSubscription.

    Possible enum values
    active

    The provisionee of this subscription is receiving servicing.

    canceled

    Servicing for this subscription is canceled.

    paused

    The servicing for the provisionee of this subscription is paused.

    pending

    The subscription is pending a successful payment and is not being serviced yet.

  • servicing_status_transitionsnullable object

    The servicing status transitions of the RateCardSubscription.

  • test_clocknullable string

    The ID of the Test Clock, if any.

Error Codes
400invalid_rate_card_subscription_status_for_update

Returned when the Update RateCardSubscription RPC is called with a status=canceled RateCardSubscription.

404rate_card_subscription_not_found

Returned when a RateCardSubscription by the provided ID cannot be found.

POST /v2/billing/rate_card_subscriptions/:id
cURL
curl -X POST https://api.stripe.com/v2/billing/rate_card_subscriptions/rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json {"metadata":{"my_key":"my_value"}}
Response
{
  "id": "rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM",
  "object": "v2.billing.rate_card_subscription",
  "billing_cadence": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
  "metadata": {
    "my_key": "my_value"
  },
  "rate_card": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "rate_card_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "collection_status": "current",
  "servicing_status": "active",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}

Retrieve a rate card subscription v2

Retrieve a RateCardSubscription by ID.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the RateCardSubscription to retrieve.

Returns

Response attributes

  • idstring

    The ID of the RateCardSubscription.

  • objectstring, value is "v2.billing.rate_card_subscription"

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

  • billing_cadencestring

    The ID of the billing Cadence.

  • collection_statusnullable enum

    The payment status of a RateCardSubscription.

    Possible enum values
    awaiting_customer_action

    The subscription payment is pending and requires customer action.

    current

    The subscription is in good standing. All payments have been successfully processed.

    past_due

    The subscription is currently overdue for payment. We are actively attempting to process the payment.

    paused

    Payment collection for the subscription is temporarily paused. The subscription may be resumed in the future, but no payments are being processed at this time.

    unpaid

    All attempts to collect payment for the subscription have been unsuccessful, and the outstanding balance is marked as uncollectible.

  • collection_status_transitionsnullable object

    The collection status transitions of the RateCardSubscription.

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

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

  • rate_cardstring

    The ID of the RateCard.

  • rate_card_versionstring

    The ID of the RateCardVersion.

  • servicing_statusnullable enum

    The servicing status of a RateCardSubscription.

    Possible enum values
    active

    The provisionee of this subscription is receiving servicing.

    canceled

    Servicing for this subscription is canceled.

    paused

    The servicing for the provisionee of this subscription is paused.

    pending

    The subscription is pending a successful payment and is not being serviced yet.

  • servicing_status_transitionsnullable object

    The servicing status transitions of the RateCardSubscription.

  • test_clocknullable string

    The ID of the Test Clock, if any.

Error Codes
404rate_card_subscription_not_found

Returned when a RateCardSubscription by the provided ID cannot be found.

GET /v2/billing/rate_card_subscriptions/:id
curl https://api.stripe.com/v2/billing/rate_card_subscriptions/rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"
Response
{
  "id": "rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM",
  "object": "v2.billing.rate_card_subscription",
  "billing_cadence": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
  "metadata": {},
  "rate_card": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "rate_card_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "collection_status": "current",
  "servicing_status": "active",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": false
}

List rate card subscriptions v2

List all RateCardSubscription objects.

Learn more about calling API v2 endpoints.

Parameters

  • billing_cadencestring

    Optionally filter by a BillingCadence. Mutually exclusive with payers, rate_card, and rate_card_version.

  • limitinteger

    The page size limit, if not provided the default is 20.

  • pagestring

    The pagination token.

  • payerobject

    Optionally filter by the payer associated with Cadences which the RateCardSubscriptions are subscribed to. Mutually exclusive with billing_cadence, rate_card, and rate_card_version.

  • rate_cardstring

    Optionally filter by a RateCard. Mutually exclusive with billing_cadence, payers, and rate_card_version.

  • rate_card_versionstring

    Optionally filter by a RateCard version. Mutually exclusive with billing_cadence, payers, and rate_card.

  • servicing_statusenum

    Optionally filter by servicing status.

    Possible enum values
    active

    The provisionee of this subscription is receiving servicing.

    canceled

    Servicing for this subscription is canceled.

    paused

    The servicing for the provisionee of this subscription is paused.

    pending

    The subscription is pending a successful payment and is not being serviced yet.

Returns

Response attributes

  • dataarray of objects

    The retrieved RateCardSubscriptions.

  • next_page_urlnullable string

    The URL to retrieve the next page if there are more RateCardSubscriptions to retrieve.

  • previous_page_urlnullable string

    The URL to retrieve the previous page if this is not the first page.

Error Codes
404billing_cadence_not_found

Returned when the provided billing_cadence ID cannot be found.

404customer_not_found

Returned when the customer for the provided ID cannot be found.

404rate_card_not_found

Returned when the provided rate_card ID cannot be found.

404rate_card_subscription_not_found

Returned when a RateCardSubscription by the provided ID cannot be found.

404rate_card_version_not_found

Returned when the provided rate_card_version ID cannot be found.

GET /v2/billing/rate_card_subscriptions
curl https://api.stripe.com/v2/billing/rate_card_subscriptions \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"
Response
{
  "data": [
    {
      "id": "rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM",
      "object": "v2.billing.rate_card_subscription",
      "billing_cadence": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
      "metadata": {},
      "rate_card": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
      "rate_card_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
      "collection_status": "current",
      "servicing_status": "active",
      "created": "2024-11-26T16:33:03.000Z",
      "livemode": true
    }
  ]
}

Cancel a rate card subscription v2

Cancel an existing, active RateCardSubscription.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the RateCardSubscription to cancel.

Returns

Response attributes

  • idstring

    The ID of the RateCardSubscription.

  • objectstring, value is "v2.billing.rate_card_subscription"

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

  • billing_cadencestring

    The ID of the billing Cadence.

  • collection_statusnullable enum

    The payment status of a RateCardSubscription.

    Possible enum values
    awaiting_customer_action

    The subscription payment is pending and requires customer action.

    current

    The subscription is in good standing. All payments have been successfully processed.

    past_due

    The subscription is currently overdue for payment. We are actively attempting to process the payment.

    paused

    Payment collection for the subscription is temporarily paused. The subscription may be resumed in the future, but no payments are being processed at this time.

    unpaid

    All attempts to collect payment for the subscription have been unsuccessful, and the outstanding balance is marked as uncollectible.

  • collection_status_transitionsnullable object

    The collection status transitions of the RateCardSubscription.

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

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

  • rate_cardstring

    The ID of the RateCard.

  • rate_card_versionstring

    The ID of the RateCardVersion.

  • servicing_statusnullable enum

    The servicing status of a RateCardSubscription.

    Possible enum values
    active

    The provisionee of this subscription is receiving servicing.

    canceled

    Servicing for this subscription is canceled.

    paused

    The servicing for the provisionee of this subscription is paused.

    pending

    The subscription is pending a successful payment and is not being serviced yet.

  • servicing_status_transitionsnullable object

    The servicing status transitions of the RateCardSubscription.

  • test_clocknullable string

    The ID of the Test Clock, if any.

Error Codes
400invalid_rate_card_subscription_status_for_cancel

Returned when the Cancel RateCardSubscription RPC is called with a status=canceled RateCardSubscription.

404rate_card_subscription_not_found

Returned when a RateCardSubscription by the provided ID cannot be found.

POST /v2/billing/rate_card_subscriptions/:id/cancel
curl -X POST https://api.stripe.com/v2/billing/rate_card_subscriptions/rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM/cancel \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"
Response
{
  "id": "rcds_test_61Rc0Iuz3V1KJFCSG16RM8VQESSQ4t1K5KYFAmKUS7XM",
  "object": "v2.billing.rate_card_subscription",
  "billing_cadence": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
  "metadata": {},
  "rate_card": "rcd_test_61Rc0EnUkb3UIaPVQ16RM8VQESSQ4t1K5KYFAmKUSUCG",
  "rate_card_version": "rcdv_test_61Rc0EnbIs6eHyCWW16RM8VQESSQ4t1K5KYFAmKUS2Nk",
  "collection_status": "current",
  "servicing_status": "canceled",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}