braintree Subscriptions API
Operations for creating, retrieving, updating, canceling, and retrying customer subscriptions to recurring billing plans.
OpenAPI Specification
openapi: 3.1.0
info:
title: Braintree Payments Add-Ons Subscriptions API
description: The Braintree Payments API is the core server-side interface for accepting and processing payments through Braintree's gateway. It enables developers to create and manage transactions, handle authorizations and captures, and process refunds and voids. The API supports a wide range of payment methods including credit and debit cards, PayPal, Apple Pay, Google Pay, and Venmo. Authentication uses HTTP Basic auth with the merchant's public key as the username and private key as the password. All requests and responses use XML or JSON depending on the SDK and endpoint variant used.
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:
schemas:
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
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.
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
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
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
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'
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
responses:
Unauthorized:
description: Unauthorized. Authentication credentials are missing or invalid.
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'
UnprocessableEntity:
description: Unprocessable entity. The request was well-formed but failed validation.
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'
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 Payments API Reference
url: https://developer.paypal.com/braintree/docs/guides/overview