# RecurringBillingSubscription

Object · GraphQL API

Represents a user's subscription record, containing billing status, pricing details, and lifecycle timing within a specific merchant account.

## Fields

- `id` (`ID!`) — non-null: The unique identifier for this subscription.
- `legacyId` (`ID!`) — non-null: The legacy subscription identifier.
- `payPalDescription` (`String`): The description of the transaction displayed to customers in PayPal email receipts.
- `status` (`RecurringBillingSubscriptionStatus!`) — non-null: The current lifecycle state of the subscription.
- `price` (`Amount!`) — non-null: The base price and currency for this subscription.
- `balance` (`Amount!`) — non-null: The amount of outstanding charges associated with a subscription.
- `billingDayOfMonth` (`Int!`) — non-null: The day of the month when the subscription will be charged on every billing cycle. Valid values are 1-28 or 31 (31 represents the last day of the month).
- `currentBillingCycle` (`Int!`) — non-null: The subscription's current billing cycle. It is incremented each time the subscription passes the billingPeriodEndDate.
- `numberOfBillingCycles` (`Int`): The number of billing cycles to execute. A value of 0 indicates it never expires.
- `failureCount` (`Int!`) — non-null: The number of consecutive failed charge attempts by the recurring billing engine. Increments with each failed attempt and resets to 0 after a successful charge.
- `daysPastDue` (`Int`): The number of days that the subscription is past due.
- `timeline` (`RecurringBillingSubscriptionTimeline!`) — non-null: Timeline information including billing dates and payment status.
- `nextBillingPeriodAmount` (`Amount`): The total subscription amount for the next billing period. This amount includes add-ons and discounts but does not include the current balance.
- `trial` (`RecurringBillingSubscriptionTrial`): Trial period settings for this subscription. Empty indicates there is no trial.
- `descriptor` (`RecurringBillingSubscriptionDescriptor`): The descriptive value on bank statements. This value may comprise static or dynamic information, and is passed on a per-transaction basis.
- `planId` (`ID!`) — non-null: The plan identifier.
- `paymentMethodId` (`ID`): The payment method to use for this subscription. Accepts single-use or vaulted payment methods.
- `merchantAccountId` (`ID`): The merchant account ID used for the subscription.
- `addOns` (`[RecurringBillingSubscriptionAddOn!]`): The collection of add-ons associated with this subscription.
- `discounts` (`[RecurringBillingSubscriptionDiscount!]`): The collection of discounts associated with this subscription.
- `transactionIds` (`[ID!]`): IDs of 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 transaction IDs; otherwise, it contains all transaction IDs associated with the subscription.
- `statusHistory` (`[RecurringBillingSubscriptionStatusEvent!]`): Array of up to 50 subscription history events.

## Used by

- [Node](/braintree/graphql/reference/types/node) — Interface; Possible type
- [RecurringBillingSubscriptionConnectionEdge](/braintree/graphql/reference/types/recurring-billing-subscription-connection-edge) — Object; node
- [RecurringBillingSubscriptionPayload](/braintree/graphql/reference/types/recurring-billing-subscription-payload) — Object; subscription

## GraphQL definition

```graphql
type RecurringBillingSubscription implements Node {
  id: ID!
  legacyId: ID!
  payPalDescription: String
  status: RecurringBillingSubscriptionStatus!
  price: Amount!
  balance: Amount!
  billingDayOfMonth: Int!
  currentBillingCycle: Int!
  numberOfBillingCycles: Int
  failureCount: Int!
  daysPastDue: Int
  timeline: RecurringBillingSubscriptionTimeline!
  nextBillingPeriodAmount: Amount
  trial: RecurringBillingSubscriptionTrial
  descriptor: RecurringBillingSubscriptionDescriptor
  planId: ID!
  paymentMethodId: ID
  merchantAccountId: ID
  addOns: [RecurringBillingSubscriptionAddOn!]
  discounts: [RecurringBillingSubscriptionDiscount!]
  transactionIds: [ID!]
  statusHistory: [RecurringBillingSubscriptionStatusEvent!]
}
```

---

[View the complete GraphQL schema on GitHub](https://raw.githubusercontent.com/braintree/graphql-api/refs/heads/master/schema.graphql)