The Intent object

Attributes

idstring
Unique identifier for the object.

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 Billing Intent.

cadencenullable string
ID of an existing Cadence to use.

createdtimestamp
Time at which the object was created.

currencystring
Three-letter ISO currency code, in lowercase. Must be a supported currency.

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 Billing Intent.
Possible enum values
canceled
The Billing Intent is canceled.
committed
The Billing Intent is committed.
draft
The Billing Intent is in draft state.
reserved
The Billing Intent is reserved.

status_transitionsobject
Timestamps for status transitions of the Billing Intent.

The Intent object

{
  "amount_details": {
    "currency": "usd",
    "discount": 0,
    "shipping": 0,
    "subtotal": 0,
    "tax": 0,
    "total": 0
  },
  "created": "2025-01-01T00:00:00.000Z",
  "currency": "usd",
  "effective_at": "current_billing_period_start",
  "id": "bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "object": "v2.billing.billing_intent",
  "status": "draft",
  "status_transitions": {
    "canceled_at": null,
    "committed_at": null,
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": null
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
}

The IntentAction object

Attributes

idstring
Unique identifier for the object.

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

applynullable objectPreview feature
Details for an apply action.

createdtimestamp
Time at which the object was created.

deactivatenullable object
Details for a deactivate action.

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

modifynullable object
Details for a modify action.

removenullable objectPreview feature
Details for a remove action.

subscribenullable object
Details for a subscribe action.

typeenum

Type of the Billing Intent Action.

Possible enum values

apply

Action to apply any adjustments, such as adding an inline discount.

deactivate

Action to deactivate an existing subscription.

modify

Action to modify an existing subscription.

remove

Action to remove adjustments, such as removing a discount.

subscribe

Action to create a new subscription.

The IntentAction object

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "bilinti_61T9VNT6aGFjxfNPx16SBbsMNLSQJnWcho4VDz0fYVOq",
  "object": "v2.billing.intent_action",
  "type": "subscribe",
  "livemode": true,
  "subscribe": {
    "type": "pricing_plan_subscription_details",
    "pricing_plan_subscription_details": {
      "component_configurations": [],
      "metadata": {},
      "pricing_plan": "bpp_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
      "pricing_plan_version": "bppv_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
      "pricing_plan_subscription": "bpps_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
    }
  }
}

Create a billing intent v2

Create a Billing Intent.

Learn more about calling API v2 endpoints.

Parameters

actionsarray of objectsRequired
Actions to be performed by this Billing Intent.

currencystringRequired
Three-letter ISO currency code, in lowercase. Must be a supported currency.

cadencestring
ID of an existing Cadence to use.

Returns

Response attributes

idstring
Unique identifier for the object.

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 Billing Intent.

cadencenullable string
ID of an existing Cadence to use.

createdtimestamp
Time at which the object was created.

currencystring
Three-letter ISO currency code, in lowercase. Must be a supported currency.

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 Billing Intent.
Possible enum values
canceled
The Billing Intent is canceled.
committed
The Billing Intent is committed.
draft
The Billing Intent is in draft state.
reserved
The Billing Intent is reserved.

status_transitionsobject
Timestamps for status transitions of the Billing Intent.

Error Codes

400amount_too_large

Returned when the billing intent total amount due is greater than the maximum amount allowed.

400amount_too_small

Returned when the billing intent total amount due is less than the minimum amount allowed.

400billing_cadence_canceled

Returned when trying to cancel a billing cadence that has already been canceled.

400billing_cadence_inactive

Returned when trying to create or update a billing intent with an inactive billing cadence.

400cadence_currency_mismatch

Returned when trying to create a BillingIntent for a currency that is not supported by the billing cadence.

400component_configuration_invalid

Returned when trying to create a billing intent action with a component configuration for an invalid pricing plan component.

400concurrent_actions_not_allowed

Returned when trying to create a BillingIntent that involves multiple actions on the same object.

400currency_mismatch

Returned when creating a rate card subscription for a billing cadence and the rate card currency does not match the billing cadence currency.

400duplicate_actions_not_allowed

Returned when trying to create a BillingIntent with duplicate actions.

400duplicate_component_configuration

Returned when trying to create a billing intent action with multiple component configurations for the same pricing plan component.

400invalid_billing_cycle_dates

Returned by billing cadences when invalid dates for a billing cycle are set.

400invalid_customer

Returned when creating or updating a cadence with a deleted customer.

400invalid_discount_percent_off

Returned when trying to apply a discount with an invalid percent_off value.

400invalid_effective_at_timestamp

Returned when the effective_at parameter is not a past timestamp.

400invalid_pricing_plan

Returned when trying to subscribe to a pricing plan that does not have any components on the version.

400license_fee_currency_mismatch

Returned when creating a rate card subscription for a billing cadence and the rate card currency does not match the billing cadence currency.

400license_fee_servicing_interval_exceeds_billing_interval

Returned when the license fee servicing interval exceeds the billing cadence cycle length.

400manual_configuration_inactive

Returned when the ManualTaxConfiguration is inactive.

400missing_discount_function

Returned when applying a discount without a discount function.

400price_currency_mismatch_with_billing_intent

Returned when the price currency does not match the billing intent currency.

400price_interval_mismatch_billing_cadence_cycle_interval

Returned when the price interval is different than the billing cadence cycle interval.

400pricing_plan_currency_mismatch

Returned when trying to create a BillingIntent for a currency that is not supported by the PricingPlan.

400pricing_plan_inactive

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

400pricing_plan_subscription_already_exists

Returned when a user tries to create a pricing plan subscription for a billing cadence that has already subscribed to the same pricing plan.

400rate_card_subscription_already_exists

Returned when a user tries to create a rate card subscription for a billing cadence that has already subscribed to the same rate card.

400require_cadence

Returned when removing a discount without providing a cadence.

400require_cadence_or_data

Returned when applying a discount without providing a cadence or cadence_data.

400servicing_interval_exceeds_billing_interval

Returned when the rate card servicing interval exceeds the billing cadence cycle length.

400too_many_active_pricing_plan_subscriptions

Returned when a user tries to create a pricing plan subscription for a billing cadence that has already reached the limit of active pricing plan subscriptions.

400too_many_active_rate_card_subscriptions

Returned when a user tries to create a rate card subscription for a billing cadence that has already reached the limit of active subscriptions.

400too_many_billing_intent_actions

Returned when trying to create a billing intent with too many billing intent actions.

400unpriced_rate_card

Returned when no rates can be found for the given rate card ID and version.

404bill_settings_not_found

Returned when the bill settings ID cannot be found.

404bill_settings_version_not_found

Returned when the provided bill settings version ID cannot be found.

404billing_cadence_not_found

Returned when the provided billing_cadence ID cannot be found.

404collection_settings_not_found

Returned when the collection settings ID cannot be found.

404collection_settings_version_not_found

Returned when the provided collection settings version ID cannot be found.

404customer_not_found

Returned when the customer for the provided ID cannot be found.

404discount_not_found

Returned when removing a non-existent discount, or when the discount is not found for the cadence.

404manual_tax_configuration_not_found

Returned when no ManualTaxConfiguration object was found for the given ID.

404price_not_found

Returned when the provided price ID cannot be found.

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.

404pricing_plan_subscription_not_found

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

404pricing_plan_version_not_found

Returned when the provided pricing_plan_version ID cannot be found.

POST /v2/billing/intents

cURL

curl -X POST https://api.stripe.com/v2/billing/intents \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
    "currency": "usd",
    "actions": [
        {
            "type": "subscribe",
            "subscribe": {
                "type": "pricing_plan_subscription_details"
            }
        }
    ]
  }'

Response

{
  "amount_details": {
    "currency": "usd",
    "discount": 0,
    "shipping": 0,
    "subtotal": 2000,
    "tax": 200,
    "total": 2200
  },
  "created": "2025-01-01T00:00:00.000Z",
  "currency": "usd",
  "id": "bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "object": "v2.billing.billing_intent",
  "status": "draft",
  "status_transitions": {
    "canceled_at": null,
    "committed_at": null,
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": null
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
}

Retrieve a billing intent v2

Retrieve a Billing Intent.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Billing Intent to retrieve.

Returns

Response attributes

idstring
Unique identifier for the object.

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 Billing Intent.

cadencenullable string
ID of an existing Cadence to use.

createdtimestamp
Time at which the object was created.

currencystring
Three-letter ISO currency code, in lowercase. Must be a supported currency.

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 Billing Intent.
Possible enum values
canceled
The Billing Intent is canceled.
committed
The Billing Intent is committed.
draft
The Billing Intent is in draft state.
reserved
The Billing Intent is reserved.

status_transitionsobject
Timestamps for status transitions of the Billing Intent.

Error Codes

404billing_intent_not_found

Returned when billing intent is not found.

GET /v2/billing/intents/:id

Server-side language

curl https://api.stripe.com/v2/billing/intents/bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.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",
  "id": "bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy",
  "object": "v2.billing.billing_intent",
  "status": "draft",
  "status_transitions": {
    "canceled_at": null,
    "committed_at": null,
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": null
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
}

Retrieve a Billing Intent Action v2

Retrieve a Billing Intent Action.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
ID of the Billing Intent Action to retrieve.

intent_idstringRequired
The ID of the Billing Intent the Billing Intent Action belongs to.

Returns

Response attributes

idstring
Unique identifier for the object.

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

applynullable objectPreview feature
Details for an apply action.

createdtimestamp
Time at which the object was created.

deactivatenullable object
Details for a deactivate action.

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

modifynullable object
Details for a modify action.

removenullable objectPreview feature
Details for a remove action.

subscribenullable object
Details for a subscribe action.

typeenum

Type of the Billing Intent Action.

Possible enum values

apply

Action to apply any adjustments, such as adding an inline discount.

deactivate

Action to deactivate an existing subscription.

modify

Action to modify an existing subscription.

remove

Action to remove adjustments, such as removing a discount.

subscribe

Action to create a new subscription.

Error Codes

404billing_intent_action_not_found

Returned when Billing Intent Action is not found.

404billing_intent_not_found

Returned when billing intent is not found.

GET /v2/billing/intents/:id/actions/:id

cURL

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

Response

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "bilinti_61T9VNT6aGFjxfNPx16SBbsMNLSQJnWcho4VDz0fYVOq",
  "object": "v2.billing.intent_action",
  "type": "subscribe",
  "livemode": true,
  "subscribe": {
    "type": "pricing_plan_subscription_details"
  }
}

The Intent object

Attributes

idstring

objectstring, value is "v2.billing.intent"

amount_detailsobject

cadencenullable string

createdtimestamp

currencystring

livemodeboolean

statusenum

status_transitionsobject

The IntentAction object

Attributes

idstring

objectstring, value is "v2.billing.intent_action"

applynullable objectPreview feature

createdtimestamp

deactivatenullable object

livemodeboolean

modifynullable object

removenullable objectPreview feature

subscribenullable object

typeenum

Create a billing intent v2

Parameters

actionsarray of objectsRequired

currencystringRequired

cadencestring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.intent"

amount_detailsobject

cadencenullable string

createdtimestamp

currencystring

livemodeboolean

statusenum

status_transitionsobject

Retrieve a billing intent v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.intent"

amount_detailsobject

cadencenullable string

createdtimestamp

currencystring

livemodeboolean

statusenum

status_transitionsobject

Retrieve a Billing Intent Action v2

Parameters

idstringRequired

intent_idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.intent_action"

applynullable objectPreview feature

createdtimestamp

deactivatenullable object

livemodeboolean

modifynullable object

removenullable objectPreview feature

subscribenullable object

typeenum