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.
- 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
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
trueif the object exists in live mode or the valuefalseif 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 valuesactiveThe cadence is active and can have subscriptions associated.
canceledThe cadence is no longer generating invoices and has been canceled.
- test_
clocknullable string The ID of the TestClock.
Returned when the provided billing profile ID cannot be found.
Returned when creating or updating a cadence with a deleted customer.
Returned by billing cadences when invalid dates for a billing cycle are set.
Returned when creating or updating a cadence with a deleted customer.
Returned when the bill settings ID cannot be found.
Returned when the provided bill settings version ID cannot be found.
Returned when the collection settings ID cannot be found.
Returned when the provided collection settings version ID cannot be found.
Returned when the customer for the provided ID cannot be found.
{ "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}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
trueif the object exists in live mode or the valuefalseif 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 valuesactiveThe cadence is active and can have subscriptions associated.
canceledThe cadence is no longer generating invoices and has been canceled.
- test_
clocknullable string The ID of the TestClock.
Returned when the provided billing profile ID cannot be found.
Returned when creating or updating a cadence with a deleted customer.
Returned when creating or updating a cadence with a deleted customer.
Returned when the payer that is being updated on a billing cadence has a test_clock that conflicts with the current test_clock.
Returned when the bill settings ID cannot be found.
Returned when the provided bill settings version ID cannot be found.
Returned when the provided billing_cadence ID cannot be found.
Returned when the collection settings ID cannot be found.
Returned when the provided collection settings version ID cannot be found.
Returned when the customer for the provided ID cannot be found.
{ "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 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
trueif the object exists in live mode or the valuefalseif 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 valuesactiveThe cadence is active and can have subscriptions associated.
canceledThe cadence is no longer generating invoices and has been canceled.
- test_
clocknullable string The ID of the TestClock.
Returned when the provided billing_cadence ID cannot be found.
{ "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 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.
Returned when incorrect filters are set when retrieving billing cadences.
Returned when the customer for the provided ID cannot be found.
Returned when the TestClock for the provided ID cannot be found.
{ "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 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
trueif the object exists in live mode or the valuefalseif 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 valuesactiveThe cadence is active and can have subscriptions associated.
canceledThe cadence is no longer generating invoices and has been canceled.
- test_
clocknullable string The ID of the TestClock.
Returned when trying to cancel a billing cadence that has active subscriptions.
Returned when trying to cancel a billing cadence that has already been canceled.
Returned when the provided billing_cadence ID cannot be found.
{ "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}