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

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

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

Meter Events 

Meter events represent actions that customers take in your system. You can use meter events to bill a customer based on their usage. Meter events are associated with billing meters, which define both the contents of the event’s payload and how to aggregate those events.

Endpoints