The PricingPlanSubscription object

Attributes

idstring
Unique identifier for the object.

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 Billing Cadence this subscription is billed on.

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. This can be useful for storing additional information about the object in a structured format.

pricing_planstring
The ID of the Pricing Plan for this subscription.

pricing_plan_versionstring
The ID of the Pricing Plan Version 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 Test Clock of the associated Billing 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
}

Update a pricing plan subscription 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-08-27.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
}

Retrieve a pricing plan subscription v2

Retrieve a Pricing Plan Subscription object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Pricing Plan Subscription to retrieve.

Returns

Response attributes

idstring
Unique identifier for the object.

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 Billing Cadence this subscription is billed on.

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. This can be useful for storing additional information about the object in a structured format.

pricing_planstring
The ID of the Pricing Plan for this subscription.

pricing_plan_versionstring
The ID of the Pricing Plan Version 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 Test Clock of the associated Billing Cadence, if any.

Error Codes

404pricing_plan_subscription_not_found

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

GET /v2/billing/pricing_plan_subscriptions/:id

Server-side language

curl https://api.stripe.com/v2/billing/pricing_plan_subscriptions/bpps_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview"

Response

{
  "billing_cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "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": {
    "order-id": "1234567890"
  },
  "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
}

List pricing plan subscriptions v2

List all Pricing Plan Subscription objects.

Learn more about calling API v2 endpoints.

Parameters

billing_cadencestring
Filter by Billing Cadence ID. Mutually exclusive with payer, pricing_plan, and pricing_plan_version.

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

pagestring
A cursor for use in pagination.

payerobject
Filter by payer. Mutually exclusive with billing_cadence, pricing_plan, and pricing_plan_version.

pricing_planstring
Filter by PricingPlan ID. Mutually exlcusive with billing_cadence, payer, and pricing_plan_version.

pricing_plan_versionstring
Filter by Pricing Plan Version ID. Mutually exlcusive with billing_cadence, payer, and pricing_plan.

servicing_statusenum

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
List of Pricing Plan Subscriptions.

next_page_urlnullable string
The URL to get the next page of results, if there are any.

previous_page_urlnullable string
The URL to get the previous page of results, if there are any.

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.

404pricing_plan_not_found

Returned when the provided pricing_plan ID cannot be found.

404pricing_plan_version_not_found

Returned when the provided pricing_plan_version ID cannot be found.

GET /v2/billing/pricing_plan_subscriptions

Server-side language

curl https://api.stripe.com/v2/billing/pricing_plan_subscriptions \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview"

Response

{
  "data": [
    {
      "billing_cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
      "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
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Cancel a pricing plan subscription v2

Cancel a PricingPlanSubscription.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the PricingPlanSubscription to cancel.

cancellation_scheduled_forenum

Optionally, schedule the PricingPlanSubscription to be canceled in the future.

Possible enum values

max_servicing_period_end

Subscription will be canceled at the latest occuring end of a servicing period.

min_servicing_period_end

Subscription will be canceled at the earliest occuring end of a servicing period.

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_cancel

Returned when trying to cancel 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/cancel

cURL

curl -X POST https://api.stripe.com/v2/billing/pricing_plan_subscriptions/bpps_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/cancel \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview"

Response

{
  "billing_cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "collection_status": "current",
  "collection_status_transitions": {
    "awaiting_customer_action_at": null,
    "current_at": "2024-12-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": "2024-12-01T00:00:00.000Z",
    "canceled_at": null,
    "paused_at": null
  },
  "test_clock": "clock_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "livemode": true
}

The PricingPlanSubscription object

Attributes

idstring

objectstring, value is "v2.billing.pricing_plan_subscription"

billing_cadencestring

collection_statusenum

collection_status_transitionsobject

createdtimestamp

livemodeboolean

metadatanullable map

pricing_planstring

pricing_plan_versionstring

servicing_statusenum

servicing_status_transitionsobject

test_clocknullable string

Update a pricing plan subscription 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

Retrieve a pricing plan subscription v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.pricing_plan_subscription"

billing_cadencestring

collection_statusenum

collection_status_transitionsobject

createdtimestamp

livemodeboolean

metadatanullable map

pricing_planstring

pricing_plan_versionstring

servicing_statusenum

servicing_status_transitionsobject

test_clocknullable string

List pricing plan subscriptions v2

Parameters

billing_cadencestring

limitinteger

pagestring

payerobject

pricing_planstring

pricing_plan_versionstring

servicing_statusenum

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

Cancel a pricing plan subscription v2

Parameters

idstringRequired

cancellation_scheduled_forenum

Returns

Response attributes

idstring

objectstring, value is "v2.billing.pricing_plan_subscription"

billing_cadencestring

cancellation_scheduled_fornullable timestamp

collection_statusenum

collection_status_transitionsobject

createdtimestamp