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

List Billing Intent Actions v2

List Billing Intent Actions.

Learn more about calling API v2 endpoints.

Parameters

intent_idstringRequired
ID of the Billing Intent to list Billing Intent Actions for.

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

pagestring
Opaque page token.

Returns

Response attributes

dataarray of objects
List of Billing Intent Actions.

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_intent_not_found

Returned when billing intent is not found.

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

cURL

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

Response

{
  "data": [
    {
      "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"
      }
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

List Billing Intents v2

List Billing Intents.

Learn more about calling API v2 endpoints.

Parameters

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

pagestring
Opaque page token.

Returns

Response attributes

dataarray of objects
List of Billing Intent objects.

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.

GET /v2/billing/intents

Server-side language

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

Response

{
  "data": [
    {
      "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"
    }
  ],
  "next_page_url": null,
  "previous_page_url": null
}

Cancel a billing intent v2

Cancel a Billing Intent.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Billing Intent to cancel.

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

400invalid_status_for_cancel

Returned when billing intent is committed or canceled.

404billing_intent_not_found

Returned when billing intent is not found.

POST /v2/billing/intents/:id/cancel

Server-side language

curl -X POST https://api.stripe.com/v2/billing/intents/bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/cancel \
  -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": "canceled",
  "status_transitions": {
    "canceled_at": "2025-01-05T00:00:00.000Z",
    "committed_at": null,
    "drafted_at": "2025-01-01T00:00:00.000Z",
    "reserved_at": null
  },
  "livemode": true,
  "cadence": "bc_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy"
}

Commit a billing intent v2

Commit a Billing Intent.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Billing Intent to commit.

payment_intentstring
ID of the PaymentIntent associated with this commit.

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

400invalid_status_for_commit

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

400payment_intent_amount_invalid

Returned when the payment intent does not have an amount matching the billing intent’s total amount.

400payment_intent_customer_invalid

Returned when the payment intent customer does not match the billing cadence payer.

400payment_intent_status_invalid

Returned when the payment intent does not have a succeeded status.

400payment_not_required

Returned when a payment intent is provided for a billing intent with a non-positive total amount.

400payment_not_required_for_send_invoice

Returned when a payment intent is provided and the billing cadence has a send_invoice collection setting.

400payment_required_to_commit

Returned when a payment intent is required to commit the billing intent.

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.

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

Server-side language

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

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

List Billing Intent Actions v2

Parameters

intent_idstringRequired

limitinteger

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

List Billing Intents v2

Parameters

limitinteger

pagestring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

Cancel 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

Commit a billing intent v2

Parameters

idstringRequired

payment_intentstring

Returns

Response attributes

idstring

objectstring, value is "v2.billing.intent"

amount_detailsobject

cadencenullable string

createdtimestamp

currencystring

livemodeboolean

statusenum

status_transitionsobject