Returned directly or within a successful result object from the following requests:
- Subscription: Create
- Subscription: Cancel
- Subscription: Update
- Subscription: Find
- Subscription: Search
- Subscription: Retry Charge
Attributes
billing_day_of_month
int
The value that specifies the day of the month that the gateway will charge the subscription on every billing cycle.
billing_period_end_date
The end date for the current billing period, regardless of subscription status. Automatic retries on past due subscriptions do not change the start and end dates of the current billing period.
billing_period_start_date
The start date for the current billing period, regardless of subscription status. Automatic retries on past due subscriptions do not change the start and end dates of the current billing period.
current_billing_cycle
int
The subscription's current billing cycle. It is incremented each time the subscription passes the billing_period_end_date
.
days_past_due
int
The number of days that the subscription is past due. Read more about the past due status in the Recurring Billing guide.
description
str
The description of the transaction that is displayed to customers in email receipts from PayPal. 127 character maximum.
descriptor
The descriptive value on bank statements. This value may comprise static or dynamic information, and is passed on a per-transaction basis. See the descriptor of Transaction: Sale for more information.
discounts
Array of Discount
objects
The collection of Discount
objects associated with a subscription.
failure_count
int
The number of consecutive failed attempts by our recurring billing engine to charge a subscription. This count includes the transaction attempt that caused the subscription's status to become past due, starting at 0 and increasing for each failed attempt. If the subscription is active and no charge attempts failed, the count is 0.
id
str
The string value representing a specific subscription in the Vault. Length and format of gateway-generated tokens and IDs may change at any time.
merchant_account_id
str
The merchant account ID used for the subscription. Currency is also determined by merchant account ID.
never_expires
bool
Whether a subscription's billing cycle is set to never expire instead of running for a specific number of billing cycles.
next_billing_date
The date that the gateway will try to bill the subscription again. The gateway adjusts this date each time it tries to charge the subscription. If the subscription is past due
and you have set your processing options to automatically retry failed transactions, the gateway will continue to adjust this date, advancing it based on the settings that you configured in advanced settings.
next_billing_period_amount
Decimal
The total subscription amount for the next billing period. This amount includes add-ons and discounts but does not include the current balance.
paid_through_date
The date through which the subscription has been paid. It is the billing_period_end_date
at the time of the last successful transaction. If the subscription is pending (has a future start date), this field is None
.
payment_method_token
str
An alphanumeric value that references a specific payment method stored in your Vault.
status
str
See the recurring billing overview. Possible values:
- braintree.Subscription.Status.Active,
- braintree.Subscription.Status.Canceled,
- braintree.Subscription.Status.Expired,
- braintree.Subscription.Status.PastDue,
- braintree.Subscription.Status.Pending
transactions
Array of Transaction
objects
Transactions associated with the subscription, sorted by creation date with the most recent first. When returned in a subscription webhook, this array contains only the 20 most recent transactions; otherwise, it contains all transactions associated with the subscription.
trial_duration_unit
str
The trial unit specified in a plan. Specify day
or month
. Specifying a trial duration unit via the API will override the subscription's plan details.
Subscription history
Each subscription history object returned on a subscription includes the following details:
Field Name | Description |
---|---|
balance |
The balance of the subscription. |
price |
The price of the subscription. |
status |
The subscription status. Possible values:
|
subscription_source |
Where the subscription event was created. Possible values:
|
Here's an example of how to get a subscription's history using the Subscription: Find method:
subscription = gateway.subscription.find("a_subscription_id")
subscription.status_history[0].balance
#=> "12.34"