Braintree Subscriptions API

openapi: 3.1.0
info:
  title: Braintree Subscriptions API
  description: >-
    The Braintree Subscriptions API enables merchants to manage recurring billing
    plans and customer subscriptions. Merchants define billing plans with
    configurable pricing, billing cycles, and trial periods, then subscribe
    customers using vaulted payment method tokens. The API handles automatic
    charge retries, prorated billing for mid-cycle changes, add-ons and discounts,
    and subscription lifecycle events. Subscription status changes are communicated
    via webhook notifications. Authentication uses HTTP Basic auth with the
    merchant's public key as the username and private key as the password.
  version: '1.0'
  contact:
    name: Braintree Developer Support
    url: https://developer.paypal.com/braintree/docs/
  termsOfService: https://www.braintreepayments.com/legal
externalDocs:
  description: Braintree Recurring Billing Documentation
  url: https://developer.paypal.com/braintree/docs/guides/recurring-billing/overview
servers:
  - url: https://api.braintreegateway.com/merchants/{merchantId}
    description: Production Server
    variables:
      merchantId:
        description: The unique identifier for the merchant account.
        default: your_merchant_id
  - url: https://api.sandbox.braintreegateway.com/merchants/{merchantId}
    description: Sandbox Server
    variables:
      merchantId:
        description: The unique identifier for the sandbox merchant account.
        default: your_merchant_id
tags:
  - name: Add-Ons
    description: >-
      Operations for retrieving add-on definitions that can be applied to
      subscriptions to increase their price.
  - name: Discounts
    description: >-
      Operations for retrieving discount definitions that can be applied to
      subscriptions to reduce their price.
  - name: Plans
    description: >-
      Operations for retrieving billing plan definitions configured in the
      Braintree Control Panel.
  - name: Subscriptions
    description: >-
      Operations for creating, retrieving, updating, canceling, and retrying
      customer subscriptions to recurring billing plans.
security:
  - basicAuth: []
paths:
  /plans:
    get:
      operationId: listPlans
      summary: List plans
      description: >-
        Returns all recurring billing plans configured for the merchant account
        in the Braintree Control Panel. Plans define the billing cycle frequency,
        base price, currency, and optional trial period for subscriptions. Plans
        must be created through the Control Panel and cannot be created via the
        API.
      tags:
        - Plans
      responses:
        '200':
          description: List of billing plans retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  plans:
                    type: array
                    items:
                      $ref: '#/components/schemas/Plan'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /add_ons:
    get:
      operationId: listAddOns
      summary: List add-ons
      description: >-
        Returns all add-on definitions configured for the merchant account.
        Add-ons represent incremental price increases that can be applied to
        subscriptions on top of the base plan price. Add-ons are defined in
        the Braintree Control Panel and referenced by their identifier when
        creating or updating subscriptions.
      tags:
        - Add-Ons
      responses:
        '200':
          description: List of add-on definitions retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  add_ons:
                    type: array
                    items:
                      $ref: '#/components/schemas/Modification'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /discounts:
    get:
      operationId: listDiscounts
      summary: List discounts
      description: >-
        Returns all discount definitions configured for the merchant account.
        Discounts represent price reductions that can be applied to
        subscriptions to decrease the amount charged each billing cycle.
        Discounts are defined in the Braintree Control Panel and referenced
        by their identifier when creating or updating subscriptions.
      tags:
        - Discounts
      responses:
        '200':
          description: List of discount definitions retrieved successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  discounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/Modification'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /subscriptions:
    post:
      operationId: createSubscription
      summary: Create a subscription
      description: >-
        Creates a new recurring billing subscription for a customer. Requires
        a plan_id identifying the billing plan and either a payment_method_token
        or payment_method_nonce identifying the payment method to charge each
        billing cycle. The subscription begins immediately or on a specified
        future date, optionally with a trial period. Add-ons and discounts from
        the plan can be inherited, overridden, or supplemented with new ones.
      tags:
        - Subscriptions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionRequest'
      responses:
        '201':
          description: Subscription created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /subscriptions/{subscriptionId}:
    get:
      operationId: getSubscription
      summary: Get a subscription
      description: >-
        Retrieves the full details of a specific subscription by its unique
        identifier. Returns the subscription's current status, billing details,
        applied add-ons and discounts, and up to 20 of its most recent
        associated transactions.
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Subscription retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateSubscription
      summary: Update a subscription
      description: >-
        Updates an existing subscription. Supports changing the payment method
        token, price, plan, billing day, number of billing cycles, and
        add-ons or discounts. Price changes take effect immediately with
        prorated billing applied for the current cycle. Changing the plan
        can optionally restart the billing cycle.
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubscriptionUpdateRequest'
      responses:
        '200':
          description: Subscription updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{subscriptionId}/cancel:
    put:
      operationId: cancelSubscription
      summary: Cancel a subscription
      description: >-
        Cancels an active subscription immediately. The subscription status
        transitions to Canceled and no further billing cycles will be charged.
        Cancellation is a terminal state and cannot be reversed; a new
        subscription must be created to resume billing.
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      responses:
        '200':
          description: Subscription canceled successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /subscriptions/{subscriptionId}/retry_charge:
    post:
      operationId: retrySubscriptionCharge
      summary: Retry a subscription charge
      description: >-
        Manually retries a failed subscription charge for a subscription in
        the Past Due status. An optional amount may be specified to charge
        a different amount than the current billing cycle amount. This is
        useful for resolving payment failures without waiting for the
        automatic retry schedule.
      tags:
        - Subscriptions
      parameters:
        - $ref: '#/components/parameters/SubscriptionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  type: string
                  description: >-
                    Amount to charge for this retry. If omitted, the
                    standard subscription price is charged.
                  example: '9.99'
                submit_for_settlement:
                  type: boolean
                  description: >-
                    If true, automatically submit the retry transaction for
                    settlement. Defaults to false.
                  default: false
      responses:
        '201':
          description: Subscription charge retry initiated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Subscription'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic Authentication using the merchant's public API key as the
        username and private API key as the password, Base64-encoded per
        RFC 7617.
  parameters:
    SubscriptionId:
      name: subscriptionId
      in: path
      required: true
      description: The unique identifier of the subscription.
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request. The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: >-
        Unprocessable entity. The request was well-formed but failed
        validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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–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: '#/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.
    SubscriptionUpdateRequest:
      type: object
      description: Request body for updating an existing subscription.
      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.
          example: '9.99'
        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: '#/components/schemas/ModificationCollection'
        discounts:
          $ref: '#/components/schemas/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.
    Subscription:
      type: object
      description: >-
        Represents a recurring billing subscription that charges a customer's
        vaulted payment method on a defined schedule according to a billing plan.
      properties:
        id:
          type: string
          description: Unique identifier for the subscription.
        plan_id:
          type: string
          description: The identifier of the billing plan this subscription is based on.
        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.
          example: '9.99'
        merchant_account_id:
          type: string
          description: The merchant account processing this subscription's charges.
        payment_method_token:
          type: string
          description: Token of the vaulted payment method being charged each cycle.
        payment_method_nonce:
          type: string
          description: >-
            Nonce associated with the payment method, if the subscription was
            created with a nonce.
        current_billing_cycle:
          type: integer
          description: The current billing cycle number, starting at 1.
          minimum: 1
        number_of_billing_cycles:
          type: integer
          description: >-
            Total number of billing cycles for the subscription. Null if the
            subscription never expires.
        trial_period:
          type: boolean
          description: Whether this subscription has a trial period.
        trial_duration:
          type: integer
          description: Duration of the trial period.
        trial_duration_unit:
          type: string
          description: Unit for the trial duration.
          enum:
            - day
            - month
        first_billing_date:
          type: string
          format: date
          description: Date of the first billing charge.
        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.
        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 billing occurs.
        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.
        add_ons:
          type: array
          description: Add-ons applied to this subscription.
          items:
            $ref: '#/components/schemas/AppliedModification'
        discounts:
          type: array
          description: Discounts applied to this subscription.
          items:
            $ref: '#/components/schemas/AppliedModification'
        transactions:
          type: array
          description: >-
            The most recent transactions associated with this subscription,
            up to 20.
          items:
            type: object
            description: A brief summary of a transaction associated with this subscription.
            properties:
              id:
                type: string
                description: Transaction identifier.
              amount:
                type: string
                description: Transaction amount.
              status:
                type: string
                description: Transaction status.
              created_at:
                type: string
                format: date-time
                description: When the transaction was created.
        failure_count:
          type: integer
          description: >-
            Number of consecutive failed billing attempts for the current
            billing cycle.
          minimum: 0
        descriptor:
          $ref: '#/components/schemas/Descriptor'
    Plan:
      type: object
      description: >-
        Represents a billing plan template defined in the Braintree Control
        Panel. Plans specify the recurring price, currency, billing frequency,
        and optional trial period that subscriptions inherit.
      properties:
        id:
          type: string
          description: Unique identifier for the plan used when creating subscriptions.
        name:
          type: string
          description: Human-readable name for the plan.
        description:
          type: string
          description: Detailed description of the plan.
        price:
          type: string
          description: Base price per billing cycle as a decimal string.
          example: '9.99'
        currency_iso_code:
          type: string
          description: ISO 4217 currency code for the plan price.
          example: USD
        billing_frequency:
          type: integer
          description: >-
            How often the plan bills, in units of billing_frequency_unit.
            For example, 1 with billing_frequency_unit "month" means monthly.
          minimum: 1
        number_of_billing_cycles:
          type: integer
          description: >-
            Default number of billing cycles. Null means the plan continues
            indefinitely.
        trial_period:
          type: boolean
          description: Whether subscriptions to this plan include a trial period by default.
        trial_duration:
          type: integer
          description: Default trial duration for subscriptions to this plan.
        trial_duration_unit:
          type: string
          description: Unit for the default trial duration.
          enum:
            - day
            - month
        add_ons:
          type: array
          description: Add-ons automatically applied to subscriptions using this plan.
          items:
            $ref: '#/components/schemas/AppliedModification'
        discounts:
          type: array
          description: Discounts automatically applied to subscriptions using this plan.
          items:
            $ref: '#/components/schemas/AppliedModification'
        created_at:
          type: string
          format: date-time
          description: Timestamp when the plan was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the plan was last updated.
    Modification:
      type: object
      description: >-
        A reusable add-on or discount definition configured in the Braintree
        Control Panel and available to apply to subscriptions.
      properties:
        id:
          type: string
          description: Unique identifier for the add-on or discount.
        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: The price adjustment amount as a decimal string.
          example: '1.00'
        kind:
          type: string
          description: Whether this is an add_on or a discount.
          enum:
            - add_on
            - discount
        never_expires:
          type: boolean
          description: >-
            If true, this modification applies indefinitely with no limit
            on number of billing cycles.
        number_of_billing_cycles:
          type: integer
          description: Number of billing cycles this modification applies.
          minimum: 1
        created_at:
          type: string
          format: date-time
          description: Timestamp when this modification was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when this modification was last updated.
    AppliedModification:
      type: object
      description: >-
        An add-on or discount currently applied to a subscription, including
        the inherited or overridden values.
      properties:
        id:
          type: string
          description: Identifier of the base add-on or discount definition.
        name:
          type: string
          description: Name of the modification.
        description:
          type: string
          description: Description of the modification.
        amount:
          type: string
          description: Amount applied per billing cycle as a decimal string.
          example: '1.00'
        never_expires:
          type: boolean
          description: If true, this modification applies indefinitely.
        number_of_billing_cycles:
          type: integer
          description: Number of billing cycles this modification will apply.
        current_billing_cycle:
          type: integer
          description: The billing cycle on which this modification began.
    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: '#/components/schemas/ModificationAdd'
        update:
          type: array
          description: Existing add-ons or discounts to update on the subscription.
          items:
            $ref: '#/components/schemas/ModificationUpdate'
        remove:
          type: array
          description: >-
            Identifiers of add-ons or discounts to remove from the
            subscription.
          items:
            type: string
    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.
          example: '1.00'
        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
    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.
          example: '1.00'
        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
    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
    Error:
      type: object
      description: Standard error response returned by the Braintree API.
      properties:
        message:
          type: string
          description: Human-readable description of the error.
        errors:
          type: object
          description: >-
            Nested object containing field-level validation errors organized
            by resource type.
          additionalProperties: true