{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/braintree/json-schema/braintree-subscription-request-schema.json",
  "title": "SubscriptionRequest",
  "description": "Request body for creating a new subscription. A payment_method_token or payment_method_nonce is required along with the plan_id.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/braintree-subscriptions-api-openapi.yml#/components/schemas/SubscriptionRequest",
  "type": "object",
  "required": [
    "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."
    },
    "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–28 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": "#/$defs/ModificationCollection"
    },
    "discounts": {
      "$ref": "#/$defs/ModificationCollection"
    },
    "descriptor": {
      "$ref": "#/$defs/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."
        }
      }
    }
  },
  "$defs": {
    "Descriptor": {
      "type": "object",
      "description": "Dynamic descriptor fields that appear on the customer's bank statement to identify the merchant and charge.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Merchant name as it appears on the customer's statement. Maximum 22 characters.",
          "maxLength": 22
        },
        "phone": {
          "type": "string",
          "description": "Merchant phone number as it appears on the customer's statement.",
          "maxLength": 14
        },
        "url": {
          "type": "string",
          "description": "Merchant URL as it appears on the customer's statement.",
          "maxLength": 13
        }
      }
    },
    "ModificationAdd": {
      "type": "object",
      "required": [
        "inherited_from_id"
      ],
      "description": "An add-on or discount to add to a subscription.",
      "properties": {
        "inherited_from_id": {
          "type": "string",
          "description": "Identifier of the base add-on or discount definition to inherit from."
        },
        "amount": {
          "type": "string",
          "description": "Override the base amount for this add-on or discount on this subscription."
        },
        "number_of_billing_cycles": {
          "type": "integer",
          "description": "Override the number of billing cycles for this add-on or discount.",
          "minimum": 1
        },
        "never_expires": {
          "type": "boolean",
          "description": "If true, override to apply this modification indefinitely."
        },
        "quantity": {
          "type": "integer",
          "description": "Number of times this add-on is applied per billing cycle.",
          "minimum": 1
        }
      }
    },
    "ModificationCollection": {
      "type": "object",
      "description": "A collection of add-on or discount operations to apply when creating or updating a subscription.",
      "properties": {
        "add": {
          "type": "array",
          "description": "Add-ons or discounts to add to the subscription.",
          "items": {
            "$ref": "#/$defs/ModificationAdd"
          }
        },
        "update": {
          "type": "array",
          "description": "Existing add-ons or discounts to update on the subscription.",
          "items": {
            "$ref": "#/$defs/ModificationUpdate"
          }
        },
        "remove": {
          "type": "array",
          "description": "Identifiers of add-ons or discounts to remove from the subscription.",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "ModificationUpdate": {
      "type": "object",
      "required": [
        "existing_id"
      ],
      "description": "An existing add-on or discount on a subscription to update.",
      "properties": {
        "existing_id": {
          "type": "string",
          "description": "Identifier of the existing applied modification to update."
        },
        "amount": {
          "type": "string",
          "description": "New amount override for this modification."
        },
        "number_of_billing_cycles": {
          "type": "integer",
          "description": "New number of billing cycles for this modification.",
          "minimum": 1
        },
        "never_expires": {
          "type": "boolean",
          "description": "If true, this modification applies indefinitely."
        },
        "quantity": {
          "type": "integer",
          "description": "Updated quantity for this add-on.",
          "minimum": 1
        }
      }
    }
  }
}