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

Release a reserved Billing Intent back to draft v2

Release a Billing Intent.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Billing Intent to release.

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_release

Returned when billing intent is not reserved.

404billing_intent_not_found

Returned when billing intent is not found.

POST /v2/billing/intents/:id/release_reservation

Server-side language

curl -X POST https://api.stripe.com/v2/billing/intents/bilint_61SbQ4ZVMJ2ESqq2416S40x4RVA8P2F2ShZStd6x6RCy/release_reservation \
  -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"
}

Reserve a billing intent v2

Reserve a Billing Intent.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the Billing Intent to reserve.

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.

400invalid_status_for_reserve

Returned when trying to reserve a billing intent and the status is not in draft.

404billing_intent_not_found

Returned when billing intent is not found.

POST /v2/billing/intents/:id/reserve

Server-side language

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

Alerts

A billing alert is a resource that notifies you when a certain usage threshold on a meter is crossed. For example, you might create a billing alert to notify you when a certain user made 100 API requests.

Endpoints

POST/v1/billing/alerts

GET/v1/billing/alerts/:id

GET/v1/billing/alerts

POST/v1/billing/alerts/:id/activate

POST/v1/billing/alerts/:id/archive

POST/v1/billing/alerts/:id/deactivate

Meters

Meters specify how to aggregate meter events over a billing period. Meter events represent the actions that customers take in your system. Meters attach to prices and form the basis of the bill.

Related guide: Usage based billing

Endpoints

POST/v1/billing/meters

POST/v1/billing/meters/:id

GET/v1/billing/meters/:id

GET/v1/billing/meters

POST/v1/billing/meters/:id/deactivate

POST/v1/billing/meters/:id/reactivate

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

Release a reserved Billing Intent back to draft v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.intent"

amount_detailsobject

cadencenullable string

createdtimestamp

currencystring

livemodeboolean

statusenum

status_transitionsobject

Reserve 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

Alerts

Meters