braintree Subscriptions API

openapi: 3.2.0
info:
  title: Braintree Subscriptions API
  description: The Braintree Subscriptions API enables merchants to manage recurring billing plans and customer subscriptions.
  version: '1.0'
  contact:
    name: Braintree Developer Support
    url: https://developer.paypal.com/braintree/docs/
  termsOfService: https://www.braintreepayments.com/legal
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
security:
- basicAuth: []
tags:
- name: Subscriptions
  description: Operations for creating, retrieving, updating, canceling, and retrying customer subscriptions to recurring billing plans.
paths:
  /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:
  responses:
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      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'
    BadRequest:
      description: Bad request. The request body or parameters are 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'
  schemas:
    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
    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.
    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
    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
    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.
    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
    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'
    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.
    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
  parameters:
    SubscriptionId:
      name: subscriptionId
      in: path
      required: true
      description: The unique identifier of the subscription.
      schema:
        type: string
  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.
externalDocs:
  description: Braintree Recurring Billing Documentation
  url: https://developer.paypal.com/braintree/docs/guides/recurring-billing/overview