{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/braintree/json-schema/braintree-subscription-update-request-schema.json",
  "title": "SubscriptionUpdateRequest",
  "description": "Request body for updating an existing subscription.",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/braintree-subscriptions-api-openapi.yml#/components/schemas/SubscriptionUpdateRequest",
  "type": "object",
  "properties": {
    "payment_method_token": {
      "type": "string",
      "description": "New payment method token to use for future billing cycles."
    },
    "payment_method_nonce": {
      "type": "string",
      "description": "A nonce for a new payment method to vault and use for future billing cycles."
    },
    "plan_id": {
      "type": "string",
      "description": "Change the subscription to a different billing plan."
    },
    "price": {
      "type": "string",
      "description": "Override the subscription price for future billing cycles."
    },
    "number_of_billing_cycles": {
      "type": "integer",
      "description": "Update the total number of billing cycles for the subscription.",
      "minimum": 1
    },
    "never_expires": {
      "type": "boolean",
      "description": "If true, the subscription continues indefinitely."
    },
    "billing_day_of_month": {
      "type": "integer",
      "description": "Update the day of the month on which charges occur.",
      "minimum": 1,
      "maximum": 31
    },
    "add_ons": {
      "$ref": "#/$defs/ModificationCollection"
    },
    "discounts": {
      "$ref": "#/$defs/ModificationCollection"
    },
    "options": {
      "type": "object",
      "description": "Options for the subscription update behavior.",
      "properties": {
        "prorate_charges": {
          "type": "boolean",
          "description": "If true, applies prorated charges or credits for the current billing cycle when the price changes mid-cycle."
        },
        "replace_all_add_ons": {
          "type": "boolean",
          "description": "If true, replaces all existing add-ons on the subscription with the provided add-ons collection."
        },
        "replace_all_discounts": {
          "type": "boolean",
          "description": "If true, replaces all existing discounts on the subscription with the provided discounts collection."
        },
        "revert_subscription_on_proration_failure": {
          "type": "boolean",
          "description": "If true, reverts the subscription update if the prorated charge fails."
        }
      }
    }
  },
  "$defs": {
    "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
        }
      }
    }
  }
}