Braintree Subscription

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://api-evangelist.github.io/braintree/schemas/subscription.json",
  "title": "Braintree Subscription",
  "description": "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.",
  "type": "object",
  "required": ["id", "plan_id", "status"],
  "properties": {
    "id": {
      "type": "string",
      "description": "Unique identifier for the subscription. Auto-generated by Braintree if not specified at creation.",
      "maxLength": 36
    },
    "plan_id": {
      "type": "string",
      "description": "Identifier of the billing plan this subscription is based on. Must match a plan configured in the Braintree Control Panel."
    },
    "status": {
      "type": "string",
      "description": "The current lifecycle status of the subscription.",
      "enum": ["Active", "Canceled", "Expired", "Past Due", "Pending"]
    },
    "price": {
      "type": "string",
      "description": "The amount charged per billing cycle as a decimal string. May override the plan's base price.",
      "pattern": "^\\d+\\.\\d{2}$",
      "example": "9.99"
    },
    "merchant_account_id": {
      "type": "string",
      "description": "Identifier of the Braintree merchant account used to process this subscription's charges."
    },
    "payment_method_token": {
      "type": "string",
      "description": "Token of the vaulted payment method charged each billing cycle.",
      "maxLength": 36
    },
    "current_billing_cycle": {
      "type": "integer",
      "description": "The current billing cycle number, starting at 1 on the first charge.",
      "minimum": 1
    },
    "number_of_billing_cycles": {
      "type": ["integer", "null"],
      "description": "Total number of billing cycles before the subscription expires. Null if the subscription never expires.",
      "minimum": 1
    },
    "never_expires": {
      "type": "boolean",
      "description": "If true, this subscription continues indefinitely regardless of the plan's number_of_billing_cycles setting."
    },
    "trial_period": {
      "type": "boolean",
      "description": "Whether this subscription includes a trial period before the first charge."
    },
    "trial_duration": {
      "type": ["integer", "null"],
      "description": "Duration of the trial period, measured in units specified by trial_duration_unit.",
      "minimum": 1
    },
    "trial_duration_unit": {
      "type": ["string", "null"],
      "description": "Unit for the trial duration.",
      "enum": ["day", "month", null]
    },
    "first_billing_date": {
      "type": "string",
      "format": "date",
      "description": "Date of the first billing charge. Subscriptions created with this date begin in Pending status until the date arrives."
    },
    "next_billing_date": {
      "type": "string",
      "format": "date",
      "description": "Date of the next scheduled billing charge."
    },
    "next_billing_amount": {
      "type": "string",
      "description": "Amount that will be charged on the next billing date, including applied add-ons and discounts.",
      "pattern": "^\\d+\\.\\d{2}$"
    },
    "paid_through_date": {
      "type": "string",
      "format": "date",
      "description": "The date through which the subscription has been paid. The next billing date is typically the day after this date."
    },
    "billing_day_of_month": {
      "type": "integer",
      "description": "Day of the month on which recurring charges occur. Valid values are 1–28 or 31 (31 means the last day of the month).",
      "minimum": 1,
      "maximum": 31
    },
    "failure_count": {
      "type": "integer",
      "description": "Number of consecutive failed billing attempts for the current billing cycle.",
      "minimum": 0
    },
    "add_ons": {
      "type": "array",
      "description": "Add-ons currently applied to this subscription that increase the billing amount.",
      "items": {
        "$ref": "#/$defs/AppliedModification"
      }
    },
    "discounts": {
      "type": "array",
      "description": "Discounts currently applied to this subscription that decrease the billing amount.",
      "items": {
        "$ref": "#/$defs/AppliedModification"
      }
    },
    "transactions": {
      "type": "array",
      "description": "The most recent transactions associated with this subscription, up to 20.",
      "maxItems": 20,
      "items": {
        "$ref": "#/$defs/TransactionSummary"
      }
    },
    "descriptor": {
      "$ref": "#/$defs/Descriptor",
      "description": "Dynamic descriptor fields for this subscription's charges on the customer's statement."
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the subscription was created, in ISO 8601 format."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp when the subscription was last updated, in ISO 8601 format."
    }
  },
  "$defs": {
    "AppliedModification": {
      "type": "object",
      "description": "An add-on or discount currently applied to a subscription, with its effective amount and billing cycle scope.",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifier matching the base add-on or discount definition in the Braintree Control Panel."
        },
        "name": {
          "type": "string",
          "description": "Human-readable name for this modification."
        },
        "description": {
          "type": "string",
          "description": "Description of what this add-on or discount represents."
        },
        "amount": {
          "type": "string",
          "description": "Amount applied per billing cycle as a decimal string.",
          "pattern": "^\\d+\\.\\d{2}$",
          "example": "1.00"
        },
        "never_expires": {
          "type": "boolean",
          "description": "If true, this modification continues indefinitely."
        },
        "number_of_billing_cycles": {
          "type": ["integer", "null"],
          "description": "Total number of billing cycles this modification applies. Null if it never expires.",
          "minimum": 1
        },
        "current_billing_cycle": {
          "type": "integer",
          "description": "The billing cycle on which this modification began, used to track remaining cycles.",
          "minimum": 1
        },
        "quantity": {
          "type": "integer",
          "description": "Number of times this add-on amount is applied per billing cycle.",
          "minimum": 1
        }
      }
    },
    "TransactionSummary": {
      "type": "object",
      "description": "A brief summary of a transaction associated with a subscription.",
      "required": ["id"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique transaction identifier."
        },
        "amount": {
          "type": "string",
          "description": "Transaction amount as a decimal string.",
          "pattern": "^\\d+\\.\\d{2}$"
        },
        "status": {
          "type": "string",
          "description": "Current status of this transaction.",
          "enum": [
            "authorization_expired",
            "authorized",
            "authorizing",
            "settlement_confirmed",
            "settlement_declined",
            "settlement_pending",
            "settled",
            "settling",
            "submitted_for_settlement",
            "voided",
            "processor_declined",
            "failed",
            "gateway_rejected"
          ]
        },
        "subscription_id": {
          "type": "string",
          "description": "Identifier of the subscription this transaction belongs to."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "Timestamp when this transaction was created."
        }
      }
    },
    "Descriptor": {
      "type": "object",
      "description": "Dynamic descriptor fields that appear on the cardholder's bank or credit card statement to identify the charge.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Merchant name as it appears on the customer's statement.",
          "maxLength": 22
        },
        "phone": {
          "type": "string",
          "description": "Merchant phone number as it appears on the customer's statement.",
          "maxLength": 14,
          "pattern": "^\\d{10,14}$"
        },
        "url": {
          "type": "string",
          "description": "Merchant URL as it appears on the customer's statement.",
          "maxLength": 13
        }
      }
    }
  }
}