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

Retrieve a PricingPlanSubscription v2

Retrieve a PricingPlanSubscription object.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the PricingPlanSubscription to retrieve.

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
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
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-07-30.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 PricingPlanSubscriptions v2

List all PricingPlanSubscription objects.

Learn more about calling API v2 endpoints.

Parameters

  • billing_cadencestring

    Filter by 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 PricingPlanVersion 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 PricingPlanSubscriptions.

  • 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
curl https://api.stripe.com/v2/billing/pricing_plan_subscriptions \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.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 PricingPlanSubscription 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-07-30.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
}

Commit an Intent v2

Commit a BillingIntent.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    ID of the BillingIntent to commit.

  • payment_intentstring

    ID of the PaymentIntent associated with this commit.

  • payment_recordstring

    ID of the PaymentRecord associated with this commit.

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
400invalid_status_for_commit

Returned when trying to commit a billing intent and the status is not in reserved.

404billing_intent_not_found

Returned when billing intent is not found.

404payment_intent_not_found

Returned when payment intent is not found.

404payment_record_not_found

Returned when payment record is not found.

POST /v2/billing/intents/:id/commit
curl -X POST https://api.stripe.com/v2/billing/intents/bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/commit \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"
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": "committed",
  "status_transitions": {
    "canceled_at": null,
    "committed_at": "2025-01-01T00:00:00.000Z",
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": "2025-01-01T00:00:00.000Z"
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
}

Reserve an Intent v2

Reserve a BillingIntent.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    ID of the BillingIntent to reserve.

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
400invalid_status_for_reserve

Returned when trying to reserve a billing intent and the status is not in draft.

404billing_intent_not_found

Returned when billing intent is not found.

POST /v2/billing/intents/:id/reserve
curl -X POST https://api.stripe.com/v2/billing/intents/bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/reserve \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"
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": "reserved",
  "status_transitions": {
    "canceled_at": null,
    "committed_at": null,
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": "2025-01-01T00:00:00.000Z"
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
}