Server-Side Response Objects/
Subscription

Subscription

Server-side response object returned directly or within a successful result object from the following requests:
Attributes
add_onsarray

The collection of Add On objects associated with a subscription.

balanceBigDecimal

The amount of outstanding charges associated with a subscription.

billing_day_of_monthInteger

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

billing_period_end_dateTime

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_dateTime

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.

created_atTime

The date/time the object was created. Returned in UTC.

current_billing_cycleInteger

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

days_past_dueInteger

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

descriptionString

The description of the transaction that is displayed to customers in email receipts from PayPal. 127 character maximum.

descriptormap

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.

nameString

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

phoneString

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

urlString

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

discountsarray

The collection of Discount objects associated with a subscription.

failure_countInteger

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.

first_billing_date

The day the subscription starts billing.

idString

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_idString

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_bill_amountBigDecimal

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

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_amountBigDecimal

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

number_of_billing_cyclesInteger

The number of billing cycles of the subscription.

payment_method_tokenString

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

plan_idString

The plan identifier.

priceBigDecimal

The base price specified for a subscription, formatted like "10" or "10.00".

statusString

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

transactionsarray

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_durationInteger

The trial timeframe specified in a plan.

trial_duration_unitString

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.

trial_periodbool

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.

updated_atTime

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

Subscription historyAnchorIcon

Each subscription history object returned on a subscription includes the following details:
Field NameDescription
balanceThe balance of the subscription.
priceThe price of the subscription.
status The subscription status. Possible values:
  • Active
  • Canceled
  • Expired
  • PastDue
  • Pending
subscription_source Where the subscription event was created. Possible values:
  • api
  • control_panel
  • recurring
Here's an example of how to get a subscription's history using the Subscription: Find method:
  1. Ruby
subscription = gateway.subscription.find("a_subscription_id")
status_history = subscription.status_history

status_history.first.balance
#=> "12.34"