braintree · Schema
Braintree Subscription
Represents a recurring billing subscription that automatically charges a customer's vaulted payment method on a schedule defined by a billing plan. Subscriptions support configurable trial periods, add-ons and discounts, and mid-cycle proration. Status changes are communicated through webhook notifications.
Properties
| Name | Type | Description |
|---|---|---|
| id | string | Unique identifier for the subscription. Auto-generated by Braintree if not specified at creation. |
| plan_id | string | Identifier of the billing plan this subscription is based on. Must match a plan configured in the Braintree Control Panel. |
| status | string | The current lifecycle status of the subscription. |
| price | string | The amount charged per billing cycle as a decimal string. May override the plan's base price. |
| merchant_account_id | string | Identifier of the Braintree merchant account used to process this subscription's charges. |
| payment_method_token | string | Token of the vaulted payment method charged each billing cycle. |
| current_billing_cycle | integer | The current billing cycle number, starting at 1 on the first charge. |
| number_of_billing_cycles | integernull | Total number of billing cycles before the subscription expires. Null if the subscription never expires. |
| never_expires | boolean | If true, this subscription continues indefinitely regardless of the plan's number_of_billing_cycles setting. |
| trial_period | boolean | Whether this subscription includes a trial period before the first charge. |
| trial_duration | integernull | Duration of the trial period, measured in units specified by trial_duration_unit. |
| trial_duration_unit | stringnull | Unit for the trial duration. |
| first_billing_date | string | Date of the first billing charge. Subscriptions created with this date begin in Pending status until the date arrives. |
| next_billing_date | string | Date of the next scheduled billing charge. |
| next_billing_amount | string | Amount that will be charged on the next billing date, including applied add-ons and discounts. |
| paid_through_date | string | The date through which the subscription has been paid. The next billing date is typically the day after this date. |
| billing_day_of_month | integer | Day of the month on which recurring charges occur. Valid values are 1–28 or 31 (31 means the last day of the month). |
| failure_count | integer | Number of consecutive failed billing attempts for the current billing cycle. |
| add_ons | array | Add-ons currently applied to this subscription that increase the billing amount. |
| discounts | array | Discounts currently applied to this subscription that decrease the billing amount. |
| transactions | array | The most recent transactions associated with this subscription, up to 20. |
| descriptor | object | Dynamic descriptor fields for this subscription's charges on the customer's statement. |
| created_at | string | Timestamp when the subscription was created, in ISO 8601 format. |
| updated_at | string | Timestamp when the subscription was last updated, in ISO 8601 format. |