Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

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

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