braintree · Schema

SubscriptionRequest

Request body for creating a new subscription. A payment_method_token or payment_method_nonce is required along with the plan_id.

Properties

Name	Type	Description
plan_id	string	The identifier of the billing plan to subscribe the customer to. Must match a plan configured in the Braintree Control Panel.
payment_method_token	string	Token of a vaulted payment method to use for subscription billing. Either this or payment_method_nonce is required.
payment_method_nonce	string	A one-time-use nonce representing a payment method to vault and use for billing. Either this or payment_method_token is required.
id	string	Custom identifier for the subscription. If omitted, Braintree generates a unique identifier. Maximum 36 characters.
price	string	Override the plan's base price. Must be a positive decimal string. If omitted, the plan price is used.
merchant_account_id	string	The merchant account to use for subscription billing. If omitted, the default merchant account is used.
trial_period	boolean	Whether to apply a trial period before the first billing cycle. Inherits the plan trial period settings if true.
trial_duration	integer	Duration of the trial period in trial_duration_unit units.
trial_duration_unit	string	Unit for the trial duration.
first_billing_date	string	The date of the first billing charge. If provided, the subscription begins in a pending state until this date. Must be a future date.
billing_day_of_month	integer	Day of the month on which recurring charges occur. Valid values are 1–28 or 31 (31 means the last day of each month).
number_of_billing_cycles	integer	Total number of billing cycles before the subscription expires. If omitted and never_expires is not set, uses the plan default.
never_expires	boolean	If true, the subscription continues indefinitely regardless of the plan's number_of_billing_cycles setting.
add_ons	object
discounts	object
descriptor	object
options	object	Options that modify subscription creation behavior.

View JSON Schema on GitHub

JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/SubscriptionRequest",
  "title": "SubscriptionRequest",
  "type": "object",
  "required": [
    "plan_id"
  ],
  "description": "Request body for creating a new subscription. A payment_method_token or payment_method_nonce is required along with the plan_id.",
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "The identifier of the billing plan to subscribe the customer to. Must match a plan configured in the Braintree Control Panel."
    },
    "payment_method_token": {
      "type": "string",
      "description": "Token of a vaulted payment method to use for subscription billing. Either this or payment_method_nonce is required."
    },
    "payment_method_nonce": {
      "type": "string",
      "description": "A one-time-use nonce representing a payment method to vault and use for billing. Either this or payment_method_token is required."
    },
    "id": {
      "type": "string",
      "description": "Custom identifier for the subscription. If omitted, Braintree generates a unique identifier. Maximum 36 characters.",
      "maxLength": 36
    },
    "price": {
      "type": "string",
      "description": "Override the plan's base price. Must be a positive decimal string. If omitted, the plan price is used.",
      "example": "9.99"
    },
    "merchant_account_id": {
      "type": "string",
      "description": "The merchant account to use for subscription billing. If omitted, the default merchant account is used."
    },
    "trial_period": {
      "type": "boolean",
      "description": "Whether to apply a trial period before the first billing cycle. Inherits the plan trial period settings if true."
    },
    "trial_duration": {
      "type": "integer",
      "description": "Duration of the trial period in trial_duration_unit units.",
      "minimum": 1
    },
    "trial_duration_unit": {
      "type": "string",
      "description": "Unit for the trial duration.",
      "enum": [
        "day",
        "month"
      ]
    },
    "first_billing_date": {
      "type": "string",
      "format": "date",
      "description": "The date of the first billing charge. If provided, the subscription begins in a pending state until this date. Must be a future date."
    },
    "billing_day_of_month": {
      "type": "integer",
      "description": "Day of the month on which recurring charges occur. Valid values are 1\u201328 or 31 (31 means the last day of each month).",
      "minimum": 1,
      "maximum": 31
    },
    "number_of_billing_cycles": {
      "type": "integer",
      "description": "Total number of billing cycles before the subscription expires. If omitted and never_expires is not set, uses the plan default.",
      "minimum": 1
    },
    "never_expires": {
      "type": "boolean",
      "description": "If true, the subscription continues indefinitely regardless of the plan's number_of_billing_cycles setting."
    },
    "add_ons": {
      "$ref": "#/components/schemas/ModificationCollection"
    },
    "discounts": {
      "$ref": "#/components/schemas/ModificationCollection"
    },
    "descriptor": {
      "$ref": "#/components/schemas/Descriptor"
    },
    "options": {
      "type": "object",
      "description": "Options that modify subscription creation behavior.",
      "properties": {
        "start_immediately": {
          "type": "boolean",
          "description": "If true, the first billing cycle starts immediately even if a first_billing_date is set in the future."
        }
      }
    }
  }
}