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
Sandboxes

Billing Cadences v2

A Billing Cadence describes when to bill a certain Payer.

Learn more about calling API v2 endpoints.
Endpoints

The Cadence object 

Attributes

  • idstring

    Unique identifier for the 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.

  • invoice_discount_rulesnullable array of objectsPreview feature

    The discount rules applied to all invoices for the cadence.

  • 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 Test Clock.

The Cadence object
{
  "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
}

Create a billing cadence v2

Create a Billing Cadence object.

Learn more about calling API v2 endpoints.

Parameters

  • billing_cycleobjectRequired

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

  • payerobjectRequired

    The payer determines the entity financially responsible for the bill.

  • includearray of enumsPreview feature

    Additional resource to include in the response.

    Possible enum values
    invoice_discount_rules

    Include parameter to expose discount rules on the cadence.

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

  • settingsobjectPreview feature

    The settings associated with the cadence.

Returns

Response attributes

  • idstring

    Unique identifier for the 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.

  • invoice_discount_rulesnullable array of objectsPreview feature

    The discount rules applied to all invoices for the cadence.

  • 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 Test Clock.

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_billing_cycle_dates

Returned by billing cadences when invalid dates for a billing cycle are set.

400invalid_customer

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

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.

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
cURL
curl -X POST https://api.stripe.com/v2/billing/cadences \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json '{
    "payer": {
        "type": "customer",
        "customer": "cus_61Rc0HZtJCE9h"
    },
    "billing_cycle": {
        "type": "month",
        "interval_count": 1,
        "month": {
            "day_of_month": 3,
            "time": {
                "hour": 1,
                "minute": 0,
                "second": 0
            }
        }
    }
  }'
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,
        "second": 0
      }
    }
  },
  "metadata": {},
  "status": "active",
  "test_clock": "clock_1QScHiH5wvQ9UC0VklUiPqw4",
  "created": "2024-11-26T16:33:03.000Z",
  "livemode": true
}

Update a billing 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.

  • includearray of enumsPreview feature

    Additional resource to include in the response.

    Possible enum values
    invoice_discount_rules

    Include parameter to expose discount rules on the cadence.

  • 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

    Unique identifier for the 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.

  • invoice_discount_rulesnullable array of objectsPreview feature

    The discount rules applied to all invoices for the cadence.

  • 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 Test Clock.

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_test_61Rc0IonJY96mpyHA16RM8VQESSQ4t1K5KYFAmKUSCie \
  -H "Authorization: Bearer sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" \
  -H "Stripe-Version: 2025-08-27.preview" \
  --json {"metadata":{"key":"value"}}
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": {
    "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": false
}

Retrieve a billing cadence v2

Retrieve a Billing Cadence object.

Learn more about calling API v2 endpoints.

Parameters

  • idstringRequired

    The ID of the billing Cadence to Retrieve.

  • includearray of enumsPreview feature

    Additional resource to include in the response.

    Possible enum values
    invoice_discount_rules

    Include parameter to expose discount rules on the cadence.

Returns

Response attributes

  • idstring

    Unique identifier for the 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.

  • invoice_discount_rulesnullable array of objectsPreview feature

    The discount rules applied to all invoices for the cadence.

  • 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 Test Clock.

Error Codes
404billing_cadence_not_found

Returned when the provided billing_cadence ID cannot be found.

GET /v2/billing/cadences/:id
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
}