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 PricingPlan v2

Create a PricingPlan object.

Learn more about calling API v2 endpoints.

Parameters

  • currencystringRequired

    The currency of the PricingPlan.

  • display_namestringRequired

    Display name of the PricingPlan. Maximum 250 characters.

  • tax_behaviorenumRequired

    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.

  • descriptionstring

    Description of pricing plan subscription.

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

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.

400product_catalog_unsupported_currency

Returned when the currency provided is not a valid currency.

POST /v2/billing/pricing_plans
curl -X POST https://api.stripe.com/v2/billing/pricing_plans \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "currency": "usd",
    "display_name": "Pro Pricing Plan",
    "lookup_key": "pro-pricing-plan",
    "metadata": {
        "key": "value"
    },
    "tax_behavior": "exclusive"
  }'
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
}

Create a PricingPlanComponent v2

Create a PricingPlanComponent object.

Learn more about calling API v2 endpoints.

Parameters

  • pricing_plan_idstringRequired

    The ID of the PricingPlan to add the component to.

  • typeenumRequired

    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.

  • license_feeobject

    Details if this component is a LicenseFee.

  • lookup_keystring

    An identifier that can be used to find this component.

  • metadatamap

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

  • rate_cardobject

    Details if this component is a RateCard.

  • service_actionobjectPreview feature

    Details if this component is a ServiceAction.

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

Returned when trying to add a component that already exists in the pricing plan.

400pricing_plan_component_currency_mismatch

Returned when the currency of the component does not match the currency on the pricing plan.

400pricing_plan_component_mismatched_configuration

Returned when there is a mismatched component configuration compared to the required “type” field.

400pricing_plan_component_tax_behavior_mismatch

Returned when the tax behavior of the component does not match the tax behavior on the pricing plan.

400pricing_plan_inactive

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

400too_many_active_pricing_plan_components

Returned when the pricing plan already has the maximum number of components.

400too_many_active_pricing_plan_rate_cards

Returned when the pricing plan already has the maximum number of rate cards.

404license_fee_not_found

Returned when the provided license_fee ID cannot be found.

404license_fee_version_not_found

Returned when the provided license_fee_version ID cannot be found.

404pricing_plan_not_found

Returned when the provided pricing_plan ID cannot be found.

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/pricing_plans/:id/components
curl -X POST https://api.stripe.com/v2/billing/pricing_plans/bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/components \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-07-30.preview" \
  --json '{
    "type": "license_fee",
    "license_fee": {
        "id": "licf_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
        "version": "licfv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
    },
    "lookup_key": "monthly-fee-component",
    "metadata": {
        "key": "value"
    }
  }'
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"
  }
}

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
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
}