Update a PricingPlan v2

Update a PricingPlan object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the PricingPlan to update.

activeboolean
Whether the PricingPlan is active.

descriptionstring
Description of pricing plan subscription.

display_namestring
Display name of the PricingPlan. Maximum 250 characters.

live_versionstring
The ID of the live version of the PricingPlan.

lookup_keystring
An internal key you can use to search for a particular PricingPlan. Maximum length of 200 characters.

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

Returns

Response attributes

idstring
Unique identifier for the PricingPlan.

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

activeboolean
Whether the PricingPlan is active.

createdtimestamp
Time at which the object was created.

currencystring
The currency of the PricingPlan.

descriptionnullable string
A description for pricing plan subscription. Maximum length of 250 characters.

display_namestring
Display name of the PricingPlan.

latest_versionstring
The ID of the latest version of the PricingPlan.

live_versionnullable string
The ID of the live version of the PricingPlan.

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

lookup_keynullable string
An internal key you can use to search for a particular PricingPlan. Maximum length of 200 characters.

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

tax_behaviorenum
The Stripe Tax tax behavior - whether the PricingPlan is inclusive or exclusive of tax.
Possible enum values
exclusive
Price excludes tax.
inclusive
Price includes tax.

Error Codes

400description_too_long

Returned when the provided description is longer than the maximum length of 250 characters.

400lookup_key_already_used

Returned when another object of the same type already has the given lookup key.

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.

POST /v2/billing/pricing_plans/:id

cURL

curl -X POST https://api.stripe.com/v2/billing/pricing_plans/bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "display_name": "Updated Pro Pricing Plan",
    "metadata": {
        "existing_key": "updated_value",
        "new_key": "new_value"
    },
    "lookup_key": "updated-pro-pricing-plan",
    "live_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
    "active": true
  }'

Response

{
  "active": true,
  "created": "2025-01-01T00:00:00.000Z",
  "currency": "usd",
  "display_name": "Updated Pro Pricing Plan",
  "id": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "latest_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "live_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "updated-pro-pricing-plan",
  "metadata": {
    "existing_key": "updated_value",
    "new_key": "new_value"
  },
  "object": "v2.billing.pricing_plan",
  "tax_behavior": "exclusive",
  "livemode": true
}

Update a PricingPlanComponent v2

Update a PricingPlanComponent object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the PricingPlanComponent to update.

pricing_plan_idstringRequired
The ID of the PricingPlan the component belongs to.

lookup_keystring
An identifier that can be used to find this component. Maximum length of 200 characters.

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

Returns

Response attributes

idstring
Unique identifier for the PricingPlanComponent.

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

createdtimestamp
Time at which the object was created.

license_feenullable object
Details if this component is a LicenseFee.

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

lookup_keynullable string
An internal key you can use to search for a particular PricingPlanComponent.

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

pricing_planstring
The ID of the PricingPlan this component belongs to.

pricing_plan_versionstring
The ID of the PricingPlanVersion this component belongs to.

rate_cardnullable object
Details if this component is a RateCard.

service_actionnullable objectPreview feature
Details if this component is a ServiceAction.

typeenum
The type of the PricingPlanComponent.
Possible enum values
license_fee
A LicenseFee component of a PricingPlan.
rate_card
A RateCard component of a PricingPlan.
service_action
A ServiceAction component of a PricingPlan.

Error Codes

400lookup_key_already_used

Returned when another object of the same type already has the given lookup key.

400pricing_plan_component_inactive

Returned when trying to update a pricing plan component that is not available in the latest pricing plan version.

400pricing_plan_inactive

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

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.

POST /v2/billing/pricing_plans/:id/components/:id

cURL

curl -X POST https://api.stripe.com/v2/billing/pricing_plans/bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/components/bppc_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"
    },
    "lookup_key": "updated-monthly-fee-component"
  }'

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "bppc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "updated-monthly-fee-component",
  "metadata": {
    "existing_key": "updated_value",
    "new_key": "new_value"
  },
  "object": "v2.billing.pricing_plan_component",
  "pricing_plan": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "pricing_plan_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "type": "license_fee",
  "livemode": true,
  "license_fee": {
    "id": "licf_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
    "version": "licfv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
  }
}

Retrieve a PricingPlan v2

Retrieve a PricingPlan object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the PricingPlan to retrieve.

Returns

Response attributes

idstring
Unique identifier for the PricingPlan.

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

activeboolean
Whether the PricingPlan is active.

createdtimestamp
Time at which the object was created.

currencystring
The currency of the PricingPlan.

descriptionnullable string
A description for pricing plan subscription. Maximum length of 250 characters.

display_namestring
Display name of the PricingPlan.

latest_versionstring
The ID of the latest version of the PricingPlan.

live_versionnullable string
The ID of the live version of the PricingPlan.

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

lookup_keynullable string
An internal key you can use to search for a particular PricingPlan. Maximum length of 200 characters.

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

tax_behaviorenum
The Stripe Tax tax behavior - whether the PricingPlan is inclusive or exclusive of tax.
Possible enum values
exclusive
Price excludes tax.
inclusive
Price includes tax.

Error Codes

404pricing_plan_not_found

Returned when the provided pricing_plan ID cannot be found.

GET /v2/billing/pricing_plans/:id

Server-side language

curl https://api.stripe.com/v2/billing/pricing_plans/bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

{
  "active": true,
  "created": "2025-01-01T00:00:00.000Z",
  "currency": "usd",
  "display_name": "Pro Pricing Plan",
  "id": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "latest_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "live_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "pro-pricing-plan",
  "metadata": {
    "key": "value"
  },
  "object": "v2.billing.pricing_plan",
  "tax_behavior": "exclusive",
  "livemode": true
}

Retrieve a PricingPlanComponent v2

Retrieve a PricingPlanComponent object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the PricingPlanComponent to retrieve.

pricing_plan_idstringRequired
The ID of the PricingPlan the component belongs to.

Returns

Response attributes

idstring
Unique identifier for the PricingPlanComponent.

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

createdtimestamp
Time at which the object was created.

license_feenullable object
Details if this component is a LicenseFee.

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

lookup_keynullable string
An internal key you can use to search for a particular PricingPlanComponent.

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

pricing_planstring
The ID of the PricingPlan this component belongs to.

pricing_plan_versionstring
The ID of the PricingPlanVersion this component belongs to.

rate_cardnullable object
Details if this component is a RateCard.

service_actionnullable objectPreview feature
Details if this component is a ServiceAction.

typeenum
The type of the PricingPlanComponent.
Possible enum values
license_fee
A LicenseFee component of a PricingPlan.
rate_card
A RateCard component of a PricingPlan.
service_action
A ServiceAction component of a PricingPlan.

Error Codes

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.

GET /v2/billing/pricing_plans/:id/components/:id

Server-side language

curl https://api.stripe.com/v2/billing/pricing_plans/bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/components/bppc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "bppc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "lookup_key": "monthly-fee-component",
  "metadata": {
    "key": "value"
  },
  "object": "v2.billing.pricing_plan_component",
  "pricing_plan": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "pricing_plan_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "type": "license_fee",
  "livemode": true,
  "license_fee": {
    "id": "licf_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
    "version": "licfv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
  }
}

Retrieve a PricingPlanVersion v2

Retrieve a specific version of a PricingPlan.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the PricingPlanVersion to retrieve.

pricing_plan_idstringRequired
The ID of the PricingPlan the version belongs to.

Returns

Response attributes

idstring
Unique identifier for the PricingPlanVersion.

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

createdtimestamp
Time at which the object was created.

end_datetimestamp
The timestamp when this version became inactive.

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

pricing_planstring
The ID of the PricingPlan this version belongs to.

start_datetimestamp
The timestamp when this version became active.

Error Codes

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_plans/:id/versions/:id

Server-side language

curl https://api.stripe.com/v2/billing/pricing_plans/bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/versions/bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview"

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "end_date": "2025-12-31T23:59:59.000Z",
  "id": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "object": "v2.billing.pricing_plan_version",
  "pricing_plan": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "start_date": "2025-01-01T00:00:00.000Z",
  "livemode": true
}

Update a PricingPlan v2

Parameters

idstringRequired

activeboolean

descriptionstring

display_namestring

live_versionstring

lookup_keystring

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.pricing_plan"

activeboolean

createdtimestamp

currencystring

descriptionnullable string

display_namestring

latest_versionstring

live_versionnullable string

livemodeboolean

lookup_keynullable string

metadatanullable map

tax_behaviorenum

Update a PricingPlanComponent v2

Parameters

idstringRequired

pricing_plan_idstringRequired

lookup_keystring

metadatamap

Returns

Response attributes

idstring

objectstring, value is "v2.billing.pricing_plan_component"

createdtimestamp

license_feenullable object

livemodeboolean

lookup_keynullable string

metadatanullable map

pricing_planstring

pricing_plan_versionstring

rate_cardnullable object

service_actionnullable objectPreview feature

typeenum

Retrieve a PricingPlan v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.pricing_plan"

activeboolean

createdtimestamp

currencystring

descriptionnullable string

display_namestring

latest_versionstring

live_versionnullable string

livemodeboolean

lookup_keynullable string

metadatanullable map

tax_behaviorenum

Retrieve a PricingPlanComponent v2

Parameters

idstringRequired

pricing_plan_idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.pricing_plan_component"

createdtimestamp

license_feenullable object

livemodeboolean

lookup_keynullable string

metadatanullable map

pricing_planstring

pricing_plan_versionstring

rate_cardnullable object

service_actionnullable objectPreview feature

typeenum