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

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
}

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

List PricingPlanComponents v2

List all PricingPlanComponent objects for a PricingPlan.

Learn more about calling API v2 endpoints.

Parameters

  • pricing_plan_idstringRequired

    The ID of the PricingPlan to list components for.

  • limitinteger

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

  • lookup_keysarray of strings

    Filter by lookup keys. Mutually exclusive with pricing_plan_version. You can specify up to 10 lookup keys.

  • pagestring

    A cursor for use in pagination.

  • pricing_plan_versionstring

    The ID of the PricingPlanVersion to list components for. Will use the latest version if not provided. Mutually exclusive with lookup_keys.

Returns

Response attributes

  • dataarray of objects

    List of PricingPlanComponents.

  • 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
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/components
curl 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"
Response
{
  "data": [
    {
      "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"
      }
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}