braintree Add-Ons API

openapi: 3.2.0
info:
  title: Braintree Subscriptions Add Ons 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: Add Ons
  description: Operations for retrieving add-on definitions that can be applied to subscriptions to increase their price.
paths:
  /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'
components:
  responses:
    Unauthorized:
      description: Unauthorized. Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    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.
    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
  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