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

Reserve an Intent v2

Reserve a BillingIntent.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    ID of the BillingIntent to reserve.

Returns

Response attributes

  • idstring

    Unique identifier for the BillingIntent.

  • 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 BillingIntent.

  • cadencenullable string

    ID of an existing Cadence to use.

  • cadence_datanullable object

    Data for creating a new Cadence.

  • createdtimestamp

    Time at which the object was created.

  • currencystring

    Three-letter ISO currency code, in lowercase.

  • effective_atenum

    When the BillingIntent will take effect.

    Possible enum values
    current_billing_period_start

    The BillingIntent will take effect at the start of the current billing period.

    on_commit

    The BillingIntent will take effect when committed.

    on_reserve

    The BillingIntent will take effect at the reserved time.

  • 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 BillingIntent.

    Possible enum values
    canceled

    The BillingIntent is canceled.

    committed

    The BillingIntent is committed.

    draft

    The BillingIntent is in draft state.

    reserved

    The BillingIntent is reserved.

  • status_transitionsobject

    Timestamps for status transitions of the BillingIntent.

Error Codes
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-07-30.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",
  "effective_at": "current_billing_period_start",
  "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"
}

Quote 

A Quote is a way to model prices that you’d like to provide to a customer. Once accepted, it will automatically create an invoice, subscription or subscription schedule.

Endpoints

Subscriptions 

Subscriptions allow you to charge a customer on a recurring basis.

Related guide: Creating subscriptions

Endpoints

Subscription Items 

Subscription items allow you to create customer subscriptions with more than one plan, making it easy to represent complex billing relationships.

Endpoints

Subscription Schedule 

A subscription schedule allows you to create and manage the lifecycle of a subscription by predefining expected changes.

Related guide: Subscription schedules

Endpoints