Update a Cadence v2

Update a billing Cadence object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the billing Cadence object to update.

metadatamap
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

payerobjectPreview feature
The payer determines the entity financially responsible for the bill.

settingsobjectPreview feature
The settings associated with the cadence.

Returns

Response attributes

idstring
The ID of the billing Cadence object.

objectstring, value is "v2.billing.cadence"
String representing the object’s type. Objects of the same type share the same value of the object field.

billing_cycleobject
The billing cycle is the object that defines future billing cycle dates.

createdtimestamp
Timestamp of when the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

next_billing_datenullable timestamp
The date that the billing cadence will next bill. Null if the cadence is not active.

payerobject
The payer determines the entity financially responsible for the bill.

settingsnullable objectPreview feature
The settings associated with the cadence.

statusenum
The current status of the cadence.
Possible enum values
active
The cadence is active and can have subscriptions associated.
canceled
The cadence is no longer generating invoices and has been canceled.

test_clocknullable string
The ID of the TestClock.

Error Codes

400billing_profile_not_found_for_cadence

Returned when the provided billing profile ID cannot be found.

400customer_tax_location_invalid

Returned when creating or updating a cadence with a deleted customer.

400invalid_customer

Returned when creating or updating a cadence with a deleted customer.

400invalid_test_clock_on_payer

Returned when the payer that is being updated on a billing cadence has a test_clock that conflicts with the current test_clock.

404bill_settings_not_found

Returned when the bill settings ID cannot be found.

404bill_settings_version_not_found

Returned when the provided bill settings version ID cannot be found.

404billing_cadence_not_found

Returned when the provided billing_cadence ID cannot be found.

404collection_settings_not_found

Returned when the collection settings ID cannot be found.

404collection_settings_version_not_found

Returned when the provided collection settings version ID cannot be found.

404customer_not_found

Returned when the customer for the provided ID cannot be found.

POST /v2/billing/cadences/:id

cURL

curl -X POST https://api.stripe.com/v2/billing/cadences/bc_123 \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json {"metadata":{"key":"value"}}

Response

{
  "id": "bc_123",
  "object": "v2.billing.cadence",
  "payer": {
    "type": "customer",
    "customer": "cus_61Rc0HZtJCE9h"
  },
  "billing_cycle": {
    "type": "month",
    "interval_count": 1,
    "month": {
      "day_of_month": 3,
      "time": {
        "hour": 1,
        "minute": 0
      }
    }
  },
  "metadata": {
    "key": "value"
  },
  "status": "active",
  "next_billing_date": "2025-01-03T01:00:00.000Z",
  "test_clock": "clock_1QScHiH5wvQ9UC0VklUiPqw4",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}

Retrieve a cadence v2

Retrieve a billing Cadence object.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the billing Cadence to Retrieve.

Returns

Response attributes

idstring
The ID of the billing Cadence object.

objectstring, value is "v2.billing.cadence"
String representing the object’s type. Objects of the same type share the same value of the object field.

billing_cycleobject
The billing cycle is the object that defines future billing cycle dates.

createdtimestamp
Timestamp of when the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

next_billing_datenullable timestamp
The date that the billing cadence will next bill. Null if the cadence is not active.

payerobject
The payer determines the entity financially responsible for the bill.

settingsnullable objectPreview feature
The settings associated with the cadence.

statusenum
The current status of the cadence.
Possible enum values
active
The cadence is active and can have subscriptions associated.
canceled
The cadence is no longer generating invoices and has been canceled.

test_clocknullable string
The ID of the TestClock.

Error Codes

404billing_cadence_not_found

Returned when the provided billing_cadence ID cannot be found.

GET /v2/billing/cadences/:id

Server-side language

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

Response

{
  "id": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
  "object": "v2.billing.cadence",
  "payer": {
    "type": "customer",
    "customer": "cus_61Rc0HZtJCE9h"
  },
  "billing_cycle": {
    "type": "month",
    "interval_count": 1,
    "month": {
      "day_of_month": 3,
      "time": {
        "hour": 1,
        "minute": 0
      }
    }
  },
  "metadata": {},
  "status": "active",
  "test_clock": "clock_1QScHiH5wvQ9UC0VklUiPqw4",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": false
}

List cadences v2

List all the billing Cadences.

Learn more about calling API v2 endpoints.

Parameters

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

pagestring
Opaque page token.

payerobject
If provided, only Cadences that specifically reference the payer will be returned. Mutually exclusive with test_clock.

test_clockstring
If provided, only Cadences that specifically reference the provided test clock ID (via the customer’s test clock) will be returned. Mutually exclusive with payer.

Returns

Response attributes

dataarray of objects
The retrieved Cadences.

next_page_urlnullable string
The URL of the next page of results, if there is one.

previous_page_urlnullable string
The URL of the previous page of results, if there is one.

Error Codes

400invalid_billing_cadence_filters

Returned when incorrect filters are set when retrieving billing cadences.

404customer_not_found

Returned when the customer for the provided ID cannot be found.

404test_clock_not_found

Returned when the TestClock for the provided ID cannot be found.

GET /v2/billing/cadences

Server-side language

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

Response

{
  "data": [
    {
      "id": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
      "object": "v2.billing.cadence",
      "payer": {
        "type": "customer",
        "customer": "cus_61Rc0HZtJCE9h"
      },
      "billing_cycle": {
        "type": "month",
        "interval_count": 1,
        "month": {
          "day_of_month": 3,
          "time": {
            "hour": 1,
            "minute": 0
          }
        }
      },
      "metadata": {},
      "status": "active",
      "test_clock": "clock_1QScHiH5wvQ9UC0VklUiPqw4",
      "created": "2024-11-26T16:33:03.000Z",
      "livemode": true
    }
  ]
}

Cancel a cadence v2

Cancel the billing cadence.

Learn more about calling API v2 endpoints.

Parameters

idstringRequired
The ID of the billing Cadence to cancel.

Returns

Response attributes

idstring
The ID of the billing Cadence object.

objectstring, value is "v2.billing.cadence"
String representing the object’s type. Objects of the same type share the same value of the object field.

billing_cycleobject
The billing cycle is the object that defines future billing cycle dates.

createdtimestamp
Timestamp of when the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

metadatanullable map
Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

next_billing_datenullable timestamp
The date that the billing cadence will next bill. Null if the cadence is not active.

payerobject
The payer determines the entity financially responsible for the bill.

settingsnullable objectPreview feature
The settings associated with the cadence.

statusenum
The current status of the cadence.
Possible enum values
active
The cadence is active and can have subscriptions associated.
canceled
The cadence is no longer generating invoices and has been canceled.

test_clocknullable string
The ID of the TestClock.

Error Codes

400billing_cadence_active

Returned when trying to cancel a billing cadence that has active subscriptions.

400billing_cadence_canceled

Returned when trying to cancel a billing cadence that has already been canceled.

404billing_cadence_not_found

Returned when the provided billing_cadence ID cannot be found.

POST /v2/billing/cadences/:id/cancel

Server-side language

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

Response

{
  "id": "bc_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie",
  "object": "v2.billing.cadence",
  "payer": {
    "type": "customer",
    "customer": "cus_61Rc0HZtJCE9h"
  },
  "billing_cycle": {
    "type": "month",
    "interval_count": 1,
    "month": {
      "day_of_month": 3,
      "time": {
        "hour": 1,
        "minute": 0
      }
    }
  },
  "metadata": {},
  "status": "canceled",
  "test_clock": "clock_1QScHiH5wvQ9UC0VklUiPqw4",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}

Cadence event types v2

This is a list of all public thin events we currently send for updates to Cadence, which are continually evolving and expanding. The payload of thin events is unversioned. During processing, you must fetch the versioned event from the API or fetch the resource’s current state.

Event types

Type

Filter events by type

Type

v2.billing.cadence.billed

Occurs when a billing Cadence generates an invoice.

Attributes

idstring
Unique identifier for the event.

objectstring, value is "v2.core.event"
String representing the object’s type. Objects of the same type share the same value of the object field.

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring, value is "v2.billing.cadence.billed"
The type of the event.

Fetched attributes

dataobject
Additional data about the event.

Event payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJgXYCjW0tI4frH0Z16RuKJoESSQUtPVJKIgeI4D29yV",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.billed",
  "livemode": true,
  "related_object": {
    "id": "bc_61SJgWTDAcSAQ2Bms16RuKJoESSQUtPVJKIgeI4D24Lb",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SJgWTDAcSAQ2Bms16RuKJoESSQUtPVJKIgeI4D24Lb"
  }
}

Event handler

Server-side language

# Select a client library to see examples of
# parsing and retrieving event details.

Fetched payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJgXYCjW0tI4frH0Z16RuKJoESSQUtPVJKIgeI4D29yV",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.billed",
  "livemode": true,
  "related_object": {
    "id": "bc_61SJgWTDAcSAQ2Bms16RuKJoESSQUtPVJKIgeI4D24Lb",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SJgWTDAcSAQ2Bms16RuKJoESSQUtPVJKIgeI4D24Lb"
  },
  "data": {}
}

v2.billing.cadence.canceled

Occurs when a billing Cadence is canceled.

Attributes

idstring
Unique identifier for the event.

objectstring, value is "v2.core.event"
String representing the object’s type. Objects of the same type share the same value of the object field.

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring, value is "v2.billing.cadence.canceled"
The type of the event.

Fetched attributes

dataobject
Additional data about the event.

Event payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJfWXBiV9sH3eqG9Z16RuKJoESSQUtPVJKIgeI4D28xU",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.canceled",
  "livemode": true,
  "related_object": {
    "id": "bc_61SJfVSCzbRzP1Als16RuKJoESSQUtPVJKIgeI4D23Ka",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SJfVSCzbRzP1Als16RuKJoESSQUtPVJKIgeI4D23Ka"
  }
}

Event handler

Server-side language

# Select a client library to see examples of
# parsing and retrieving event details.

Fetched payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJfWXBiV9sH3eqG9Z16RuKJoESSQUtPVJKIgeI4D28xU",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.canceled",
  "livemode": true,
  "related_object": {
    "id": "bc_61SJfVSCzbRzP1Als16RuKJoESSQUtPVJKIgeI4D23Ka",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SJfVSCzbRzP1Als16RuKJoESSQUtPVJKIgeI4D23Ka"
  },
  "data": {}
}

v2.billing.cadence.created

Occurs when a billing Cadence is created.

Attributes

idstring
Unique identifier for the event.

objectstring, value is "v2.core.event"
String representing the object’s type. Objects of the same type share the same value of the object field.

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring, value is "v2.billing.cadence.created"
The type of the event.

Fetched attributes

dataobject
Additional data about the event.

Event payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SKkl34vlR6d24Hm1n16RuKJoESSQUtPVJKIgeI4D2UUi",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.created",
  "livemode": true,
  "related_object": {
    "id": "bc_61SKkl26v5dA6DMUC16RuKJoESSQUtPVJKIgeI4D26uW",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SKkl26v5dA6DMUC16RuKJoESSQUtPVJKIgeI4D26uW"
  }
}

Event handler

Server-side language

# Select a client library to see examples of
# parsing and retrieving event details.

Fetched payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SKkl34vlR6d24Hm1n16RuKJoESSQUtPVJKIgeI4D2UUi",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.created",
  "livemode": true,
  "related_object": {
    "id": "bc_61SKkl26v5dA6DMUC16RuKJoESSQUtPVJKIgeI4D26uW",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SKkl26v5dA6DMUC16RuKJoESSQUtPVJKIgeI4D26uW"
  },
  "data": {
    "created": "2025-01-01T00:00:00.000Z"
  }
}

v2.billing.cadence.errored

Occurs when a billing Cadence encounters an error during a tick.

Attributes

idstring
Unique identifier for the event.

objectstring, value is "v2.core.event"
String representing the object’s type. Objects of the same type share the same value of the object field.

contextnullable string
Authentication context needed to fetch the event or related object.

createdtimestamp
Time at which the object was created.

livemodeboolean
Has the value true if the object exists in live mode or the value false if the object exists in test mode.

reasonnullable object
Reason for the event.

related_objectnullable object
Object containing the reference to API resource relevant to the event.

typestring, value is "v2.billing.cadence.errored"
The type of the event.

Fetched attributes

dataobject
Additional data about the event.

Event payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJeVWAhU8rG2dpF8Z16RuKJoESSQUtPVJKIgeI4D27wT",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.errored",
  "livemode": true,
  "related_object": {
    "id": "bc_61SJeURByaQyO0zks16RuKJoESSQUtPVJKIgeI4D22JZ",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SJeURByaQyO0zks16RuKJoESSQUtPVJKIgeI4D22JZ"
  }
}

Event handler

Server-side language

# Select a client library to see examples of
# parsing and retrieving event details.

Fetched payload

{
  "created": "2025-01-01T00:00:00.000Z",
  "id": "evt_65SJeVWAhU8rG2dpF8Z16RuKJoESSQUtPVJKIgeI4D27wT",
  "object": "v2.core.event",
  "type": "v2.billing.cadence.errored",
  "livemode": true,
  "related_object": {
    "id": "bc_61SJeURByaQyO0zks16RuKJoESSQUtPVJKIgeI4D22JZ",
    "type": "v2.billing.cadence",
    "url": "/v2/billing/cadences/bc_61SJeURByaQyO0zks16RuKJoESSQUtPVJKIgeI4D22JZ"
  },
  "data": {}
}

Update a Cadence v2

Parameters

idstringRequired

metadatamap

payerobjectPreview feature

settingsobjectPreview feature

Returns

Response attributes

idstring

objectstring, value is "v2.billing.cadence"

billing_cycleobject

createdtimestamp

livemodeboolean

metadatanullable map

next_billing_datenullable timestamp

payerobject

settingsnullable objectPreview feature

statusenum

test_clocknullable string

Retrieve a cadence v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.cadence"

billing_cycleobject

createdtimestamp

livemodeboolean

metadatanullable map

next_billing_datenullable timestamp

payerobject

settingsnullable objectPreview feature

statusenum

test_clocknullable string

List cadences v2

Parameters

limitinteger

pagestring

payerobject

test_clockstring

Returns

Response attributes

dataarray of objects

next_page_urlnullable string

previous_page_urlnullable string

Cancel a cadence v2

Parameters

idstringRequired

Returns

Response attributes

idstring

objectstring, value is "v2.billing.cadence"

billing_cycleobject

createdtimestamp

livemodeboolean

metadatanullable map

next_billing_datenullable timestamp

payerobject

settingsnullable objectPreview feature

statusenum

test_clocknullable string

Cadence event types v2

Event types

Attributes

idstring

objectstring, value is "v2.core.event"

contextnullable string

createdtimestamp

livemodeboolean

reasonnullable object

related_objectnullable object

typestring, value is "v2.billing.cadence.billed"

Fetched attributes

dataobject

Attributes

idstring

objectstring, value is "v2.core.event"

contextnullable string

createdtimestamp