Returned within a successful result object from the following requests:

Attributes
addOns Array of Braintree_AddOn objects

The collection of Braintree_AddOn objects associated with a subscription.

balance String

The amount of outstanding charges associated with a subscription.

billingDayOfMonth int

The value that specifies the day of the month that the gateway will charge the subscription on every billing cycle.

billingPeriodEndDate

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.

billingPeriodStartDate

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.

createdAt DateTime

The date/time the object was created.

currentBillingCycle int

The subscription's current billing cycle. It is incremented each time the subscription passes the billingPeriodEndDate.

daysPastDue int

The number of days that the subscription is past due. Read more about the past due status in the Recurring Billing guide.

descriptor

The descriptive value on bank statements. This value may be comprised of static or dynamic information, and is passed on a per-transaction basis. See the descriptor of Braintree_Transaction::sale() for more information.

name string

The value in the business name field of a customer's statement.

phone string

The value in the phone number field of a customer's statement.

url string

The value in the URL/web address field of a customer's statement.

discounts Array of Braintree_Discount objects

The collection of Braintree_Discount objects associated with a subscription.

failureCount int

The number of consecutive failed attempts by Braintree's 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.

firstBillingDate

The day the subscription starts billing.

id string

The string value representing a specific subscription in the Vault. Length and format of gateway-generated tokens and IDs may change at any time.

merchantAccountId string

The merchant account ID used for the subscription. Currency is also determined by merchant account ID.

neverExpires bool

Whether a subscription's billing cycle is set to never expire instead of running for a specific number of billing cycles.

nextBillAmount String

Do not use. This is the deprecated version of next_billing_period_amount.

nextBillingDate

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.

nextBillingPeriodAmount String

The total subscription amount for the next billing period. This amount includes add-ons and discounts but does not include the current balance.

numberOfBillingCycles int

The number of billing cycles of the subscription.

paidThroughDate

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

paymentMethodToken string

An alphanumeric value that references a specific payment method stored in your Vault.

planId string

The plan identifier.

price String

The price specified for a plan, add-on, discount, or subscription. Billing price is formatted like "10" or "10.00".

status string

See the recurring billing overview. Possible values:

  • Braintree_Subscription::ACTIVE,
  • Braintree_Subscription::CANCELED,
  • Braintree_Subscription::EXPIRED,
  • Braintree_Subscription::PAST_DUE,
  • Braintree_Subscription::PENDING
statusHistory

Array of up to 50 subscription history events.

transactions Array of Braintree_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.

trialDuration int

The trial timeframe specified in a plan.

trialDurationUnit string

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.

trialPeriod bool

A value indicating whether a subscription should begin with a trial period. Specifying a trial period via the API will override the subscription's plan details.

updatedAt DateTime

The date/time the object was last updated. If a subscription has been canceled, this value will represent the date/time of cancellation.

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:
  • Active
  • Canceled
  • Expired
  • PastDue
  • Pending
subscriptionSource Where the subscription was created. Possible values:
  • api
  • control_panel
  • recurring

Here's an example of how to get a subscription's history using the Braintree_Subscription::find() method:

PHP
$subscription = Braintree_Subscription::find('a_subscription_id');
$status_history = $subscription->statusHistory;

$status_history[0]->balance;
#=> "12.34"

Still have questions?

If you can’t find an answer, contact our Support team.