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