Pricing Plan Subscriptions v2

A PricingPlanSubscription links a PricingPlan to a specific billing Cadence. While the PricingPlanSubscription is active, Stripe will bill the Payer according to the PricingPlan’s components.

Learn more about calling API v2 endpoints.

Endpoints

POST/v2/billing/intents

POST/v2/billing/pricing_plan_subscriptions/:id

GET/v2/billing/intents/:id

GET/v2/billing/pricing_plan_subscriptions/:id

GET/v2/billing/pricing_plan_subscriptions

POST/v2/billing/pricing_plan_subscriptions/:id/cancel

POST/v2/billing/intents/:id/commit

POST/v2/billing/intents/:id/reserve

The PricingPlanSubscription object

Attributes

idstring
Unique identifier for the PricingPlanSubscription.

objectstring, value is "v2.billing.pricing_plan_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 Cadence this subscription is billed on.

cancellation_scheduled_fornullable timestamp
Time at which this subscription will be canceled.

collection_statusenum

Current collection status of this subscription.

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_transitionsobject
Timestamps for collection status transitions.

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.

metadatanullable map
Set of key-value pairs that you can attach to an object.

pricing_planstring
The ID of the PricingPlan for this subscription.

pricing_plan_versionstring
The ID of the PricingPlanVersion for this subscription.

servicing_statusenum

Current servicing status of this subscription.

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_transitionsobject
Timestamps for servicing status transitions.

test_clocknullable string
The ID of the TestClock of the associated Cadence, if any.

The PricingPlanSubscription object

{
  "billing_cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "cancelation_scheduled_for": "2025-01-01T00:00:00.000Z",
  "collection_status": "current",
  "collection_status_transitions": {
    "awaiting_customer_action_at": null,
    "current_at": "2025-01-01T00:00:00.000Z",
    "past_due_at": null,
    "paused_at": null,
    "unpaid_at": null
  },
  "created": "2025-01-01T00:00:00.000Z",
  "id": "bpps_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "metadata": {
    "key": "value"
  },
  "object": "v2.billing.pricing_plan_subscription",
  "pricing_plan": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "pricing_plan_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "servicing_status": "active",
  "servicing_status_transitions": {
    "activated_at": "2025-01-01T00:00:00.000Z",
    "canceled_at": null,
    "paused_at": null
  },
  "test_clock": "clock_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "livemode": true
}

The Intent object

Attributes

idstring
Unique identifier for the BillingIntent.

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

amount_detailsobject
Breakdown of the amount for this BillingIntent.

cadencenullable string
ID of an existing Cadence to use.

cadence_datanullable object
Data for creating a new Cadence.

createdtimestamp
Time at which the object was created.

currencystring
Three-letter ISO currency code, in lowercase.

effective_atenum

When the BillingIntent will take effect.

Possible enum values

current_billing_period_start

The BillingIntent will take effect at the start of the current billing period.

on_commit

The BillingIntent will take effect when committed.

on_reserve

The BillingIntent will take effect at the reserved time.

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

statusenum
Current status of the BillingIntent.
Possible enum values
canceled
The BillingIntent is canceled.
committed
The BillingIntent is committed.
draft
The BillingIntent is in draft state.
reserved
The BillingIntent is reserved.

status_transitionsobject
Timestamps for status transitions of the BillingIntent.

The Intent object

{
  "amount_details": {
    "currency": "usd",
    "discount": 0,
    "shipping": 0,
    "subtotal": 0,
    "tax": 0,
    "total": 0
  },
  "created": "2025-01-01T00:00:00.000Z",
  "currency": "usd",
  "effective_at": "current_billing_period_start",
  "id": "bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "object": "v2.billing.billing_intent",
  "status": "draft",
  "status_transitions": {
    "canceled_at": null,
    "committed_at": null,
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": null
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "cadence_data": {
    "billing_cycle": {
      "interval_count": 1,
      "type": "month",
      "month": {
        "day_of_month": 1,
        "time": {
          "hour": 0,
          "minute": 0
        }
      }
    },
    "payer": {
      "billing_profile": "bilp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
      "customer": "cus_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
      "type": "customer"
    },
    "settings": {
      "bill": {
        "id": "bblset_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
        "version": "bblsetv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
      },
      "collection": {
        "id": "bclset_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
        "version": "bclsetv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
      }
    }
  }
}

Create an Intent v2

Create a BillingIntent.

Learn more about calling API v2 endpoints.

Parameters

actionsarray of objectsRequired
Actions to be performed by this BillingIntent.

currencystringRequired
Three-letter ISO currency code, in lowercase.

effective_atenumRequired

When the BillingIntent will take effect.

Possible enum values

current_billing_period_start

The BillingIntent will take effect at the start of the current billing period.

on_commit

The BillingIntent will take effect when committed.

on_reserve

The BillingIntent will take effect at the reserved time.

cadencestring
ID of an existing Cadence to use.

cadence_dataobject
Data for creating a new Cadence.

Returns

Response attributes

idstring
Unique identifier for the BillingIntent.

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

amount_detailsobject
Breakdown of the amount for this BillingIntent.

cadencenullable string
ID of an existing Cadence to use.

cadence_datanullable object
Data for creating a new Cadence.

createdtimestamp
Time at which the object was created.

currencystring
Three-letter ISO currency code, in lowercase.

effective_atenum

When the BillingIntent will take effect.

Possible enum values

current_billing_period_start

The BillingIntent will take effect at the start of the current billing period.

on_commit

The BillingIntent will take effect when committed.

on_reserve

The BillingIntent will take effect at the reserved time.

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

statusenum
Current status of the BillingIntent.
Possible enum values
canceled
The BillingIntent is canceled.
committed
The BillingIntent is committed.
draft
The BillingIntent is in draft state.
reserved
The BillingIntent is reserved.

status_transitionsobject
Timestamps for status transitions of the BillingIntent.

Error Codes

400billing_cadence_canceled

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

400cadence_currency_mismatch

Returned when trying to create a BillingIntent for a currency that is not supported by the billing cadence.

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.

400invalid_billing_cycle_dates

Returned by billing cadences when invalid dates for a billing cycle are set.

400invalid_customer

Returned when creating or updating a cadence with a deleted customer.

400invalid_discount_percent_off

Returned when trying to apply a discount with an invalid percent_off value.

400invalid_pricing_plan

Returned when trying to subscribe to a pricing plan that does not have any components on the version.

400license_fee_currency_mismatch

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

400license_fee_servicing_interval_exceeds_billing_interval

Returned when the license fee servicing interval exceeds the billing cadence cycle length.

400manual_configuration_inactive

Returned when the ManualTaxConfiguration is inactive.

400missing_discount_function

Returned when applying a discount without a discount function.

400pricing_plan_currency_mismatch

Returned when trying to create a BillingIntent for a currency that is not supported by the PricingPlan.

400pricing_plan_inactive

Returned when trying to create or modify a subscription for an inactive pricing plan.

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.

400require_cadence

Returned when removing a discount without providing a cadence.

400require_cadence_or_data

Returned when applying a discount without providing a cadence or cadence_data.

400servicing_interval_exceeds_billing_interval

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

400too_many_active_pricing_plan_subscriptions

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

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.

404bill_settings_not_found

Returned when the bill settings ID cannot be found.

404bill_settings_version_not_found

Returned when the provided bill settings version ID cannot be found.

404billing_cadence_not_found

Returned when the provided billing_cadence ID cannot be found.

404collection_settings_not_found

Returned when the collection settings ID cannot be found.

404collection_settings_version_not_found

Returned when the provided collection settings version ID cannot be found.

404customer_not_found

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

404discount_not_found

Returned when removing a non-existent discount, or when the discount is not found for the cadence.

404manual_tax_configuration_not_found

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

404pricing_plan_component_not_found

Returned when the provided pricing_plan_component ID cannot be found.

404pricing_plan_not_found

Returned when the provided pricing_plan ID cannot be found.

404pricing_plan_subscription_not_found

Returned when a pricing plan subscription with the provided ID cannot be found.

404pricing_plan_version_not_found

Returned when the provided pricing_plan_version ID cannot be found.

POST /v2/billing/intents

cURL

curl -X POST https://api.stripe.com/v2/billing/intents \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
    "currency": "usd",
    "effective_at": "current_billing_period_start",
    "actions": [
        {
            "type": "subscribe",
            "subscribe": {
                "type": "pricing_plan_subscription_details",
                "proration_behavior": "none",
                "pricing_plan_subscription_details": {
                    "pricing_plan": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
                    "pricing_plan_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
                    "component_configurations": []
                }
            }
        }
    ]
  }'

Response

{
  "amount_details": {
    "currency": "usd",
    "discount": 0,
    "shipping": 0,
    "subtotal": 2000,
    "tax": 200,
    "total": 2200
  },
  "created": "2025-01-01T00:00:00.000Z",
  "currency": "usd",
  "effective_at": "current_billing_period_start",
  "id": "bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "object": "v2.billing.billing_intent",
  "status": "draft",
  "status_transitions": {
    "canceled_at": null,
    "committed_at": null,
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": null
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
}

Update a PricingPlanSubscription v2

Update a PricingPlanSubscription object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the PricingPlanSubscription to update.

metadatamap
Set of key-value pairs that you can attach to an object.

Returns

Response attributes

idstring
Unique identifier for the PricingPlanSubscription.

objectstring, value is "v2.billing.pricing_plan_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 Cadence this subscription is billed on.

cancellation_scheduled_fornullable timestamp
Time at which this subscription will be canceled.

collection_statusenum

Current collection status of this subscription.

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_transitionsobject
Timestamps for collection status transitions.

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.

metadatanullable map
Set of key-value pairs that you can attach to an object.

pricing_planstring
The ID of the PricingPlan for this subscription.

pricing_plan_versionstring
The ID of the PricingPlanVersion for this subscription.

servicing_statusenum

Current servicing status of this subscription.

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_transitionsobject
Timestamps for servicing status transitions.

test_clocknullable string
The ID of the TestClock of the associated Cadence, if any.

Error Codes

400invalid_pricing_plan_subscription_status_for_update

Returned when trying to update a pricing plan subscription with servicing status canceled.

404pricing_plan_subscription_not_found

Returned when a pricing plan subscription with the provided ID cannot be found.

POST /v2/billing/pricing_plan_subscriptions/:id

Server-side language

curl -X POST https://api.stripe.com/v2/billing/pricing_plan_subscriptions/bpps_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "metadata": {
        "existing_key": "updated_value",
        "new_key": "new_value"
    }
  }'

Response

{
  "billing_cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "collection_status": "awaiting_customer_action",
  "collection_status_transitions": {
    "awaiting_customer_action_at": null,
    "current_at": "2025-01-01T00:00:00.000Z",
    "past_due_at": null,
    "paused_at": null,
    "unpaid_at": null
  },
  "created": "2025-01-01T00:00:00.000Z",
  "id": "bpps_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "metadata": {
    "existing_key": "updated_value",
    "new_key": "new_value"
  },
  "object": "v2.billing.pricing_plan_subscription",
  "pricing_plan": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "pricing_plan_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "servicing_status": "active",
  "servicing_status_transitions": {
    "activated_at": "2025-01-01T00:00:00.000Z",
    "canceled_at": null,
    "paused_at": null
  },
  "test_clock": "clock_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "livemode": true
}

Pricing Plan Subscriptions v2

The PricingPlanSubscription object

Attributes

idstring

objectstring, value is "v2.billing.pricing_plan_subscription"

billing_cadencestring

cancellation_scheduled_fornullable timestamp

collection_statusenum

collection_status_transitionsobject

createdtimestamp

livemodeboolean

metadatanullable map

pricing_planstring

pricing_plan_versionstring

servicing_statusenum

servicing_status_transitionsobject

test_clocknullable string

The Intent object

Attributes

idstring

objectstring, value is "v2.billing.intent"

amount_detailsobject

cadencenullable string

cadence_datanullable object

createdtimestamp

currencystring

effective_atenum

livemodeboolean

statusenum

status_transitionsobject

Create an Intent v2

Parameters

actionsarray of objectsRequired

currencystringRequired

effective_atenumRequired

cadencestring

cadence_dataobject

Returns

Response attributes

idstring

objectstring, value is "v2.billing.intent"

amount_detailsobject

cadencenullable string

cadence_datanullable object

createdtimestamp

currencystring

effective_atenum

livemodeboolean

statusenum

status_transitionsobject

Update a PricingPlanSubscription v2

Parameters

idstringRequired

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.pricing_plan_subscription"

billing_cadencestring

cancellation_scheduled_fornullable timestamp

collection_statusenum

collection_status_transitionsobject

createdtimestamp

livemodeboolean

metadatanullable map

pricing_planstring

pricing_plan_versionstring

servicing_statusenum

servicing_status_transitionsobject

test_clocknullable string