Deprecation notice: TheYou use billing plans and billing agreements to create an agreement for a recurring PayPal or debit card payment for goods or services./v1/payments/billing-plansendpoints are deprecated. Use the/v1/billing/plansendpoints instead. For details, see Subscriptions Integration.
state
to ACTIVE.Important: The use of the PayPal
REST /payments APIs to accept credit card payments is
restricted. Instead, you can accept credit card payments with Braintree
Direct.
version: "1.2"
x-serviceName: subnplanmgmtserv
x-publicDocsPath: billing-plans
externalDocs:
url: /docs/subscriptions/integrate/
servers:
- url: https://api-m.sandbox.paypal.com
description: PayPal API Sandbox
tags:
- name: billing-plans
description: Use the `/billing-plans` resource to create, update, show details
for, and list plans.
paths:
/billing-plans/{plan_id}:
get:
tags:
- billing-plans
summary: Show billing plan details
description: Shows details for a billing plan, by ID.
operationId: billing-plans.get
parameters:
- name: plan_id
in: path
description: The ID of the billing plan for which to show details.
required: true
schema:
type: string
responses:
"200":
description: A successful request returns the HTTP `200 OK` status code and a
JSON response body that shows plan details.
content:
application/json:
schema:
$ref: "#/components/schemas/plan"
default:
description: The error response.
content:
application/json:
schema:
$ref: "#/components/schemas/error"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
x-slo:
response_time_95th_percentile: 0
error_rate: 0.1
x-visibility:
extent: EXTERNAL
x-publicSDKSamples:
- language: C#
link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanGet.aspx.cs
- language: JAVA
link: https://github.com/paypal/PayPal-Java-SDK/blob/master/rest-api-sample/src/main/java/com/paypal/api/sample/SubscriptionSample.java#L74
- language: Node
link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/get.js
- language: PHP
link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/GetPlan.php
- language: Python
link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/get.py
patch:
tags:
- billing-plans
summary: Update billing plan
description: Updates fields in a billing plan, by ID. In the JSON request body,
include a patch object that specifies the operation to perform, one or
more fields to update, and a new value for each updated field.
operationId: billing-plans.patch
parameters:
- name: plan_id
in: path
description: The ID of the billing plan to update.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/patch_request"
- type: object
examples:
- - op: replace
path: /
value:
state: ACTIVE
required: false
responses:
"200":
description: A successful request returns the HTTP `200 OK` status code with no
JSON response body.
content: {}
default:
description: The error response.
content:
application/json:
schema:
$ref: "#/components/schemas/error"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
x-slo:
response_time_95th_percentile: 0
error_rate: 0.1
x-visibility:
extent: EXTERNAL
x-publicSDKSamples:
- language: C#
link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanUpdate.aspx.cs
- language: JAVA
link: https://github.com/paypal/PayPal-Java-SDK/blob/master/rest-api-sample/src/main/java/com/paypal/api/sample/SubscriptionSample.java#L51
- language: Node
link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/update.js
- language: PHP
link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/UpdatePlan.php
- language: Python
link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/replace.py
x-codegen-request-body-name: patch_request
/billing-plans:
get:
tags:
- billing-plans
summary: List billing plans
description: Lists billing plans. To filter the plans that appear in the
response, specify one or more optional query and pagination parameters.
operationId: billing-plans.list
parameters:
- name: page
in: query
description: The zero-indexed number of the first page that begins the set of
pages that are returned in the response.
schema:
type: string
default: "0"
- name: status
in: query
description: Filters the plans in the response by a plan status.
schema:
type: string
default: CREATED
enum:
- CREATED
- ACTIVE
- INACTIVE
- ALL
x-visibility:
extent: EXTERNAL
x-visibility:
extent: EXTERNAL
- name: page_size
in: query
description: The number of plans to list on a single page. For example, if
`page_size` is `10`, each page shows ten plans. A valid value is a
non-negative, non-zero integer.
schema:
type: string
default: "10"
- name: total_required
in: query
description: Indicates whether the response includes the `total_items` and
`total_pages` fields. Value is `yes` or `no`.
schema:
type: string
default: no
responses:
"200":
description: A successful request returns the HTTP `200 OK` status code and a
JSON response body that lists plans with details.
content:
application/json:
schema:
$ref: "#/components/schemas/plan_list"
default:
description: The error response.
content:
application/json:
schema:
$ref: "#/components/schemas/error"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
x-slo:
response_time_95th_percentile: 0
error_rate: 0.1
x-visibility:
extent: EXTERNAL
x-publicSDKSamples:
- language: C#
link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanGetList.aspx.cs
- language: Node
link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/list.js
- language: PHP
link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/ListPlans.php
- language: Python
link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/get_all.py
post:
tags:
- billing-plans
summary: Create billing plan
description: Creates a billing plan. In the JSON request body, include the plan
details. A plan must include at least one regular payment definition
and, optionally, a trial payment definition. Each payment definition
specifies a billing period, which determines how often and for how long
the customer is charged. A plan can specify a fixed or infinite number
of payment cycles. A payment definition can optionally specify shipping
fee and tax amounts. The default state of a new plan is `CREATED`.
Before you can create an agreement from a plan, you must activate the
plan by updating its `state` to `ACTIVE`.
operationId: billing-plans.post
requestBody:
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/plan"
- type: object
examples:
- name: Simple Plan
description: Plan with one regular payment definition, minimal merchant
preferences, and no shipping fees or tax.
type: FIXED
payment_definitions:
- name: Regular payment definition
type: REGULAR
frequency: MONTH
frequency_interval: "2"
amount:
value: "100"
currency: USD
cycles: "12"
merchant_preferences:
return_url: https://example.com
cancel_url: https://example.com/cancel
required: false
responses:
"201":
description: A successful request returns the HTTP `201 Created` status code and
a JSON response body that shows plan details.
content:
application/json:
schema:
$ref: "#/components/schemas/plan"
default:
description: The error response.
content:
application/json:
schema:
$ref: "#/components/schemas/error"
security:
- Oauth2:
- https://uri.paypal.com/services/subscriptions
x-slo:
response_time_95th_percentile: 0
error_rate: 0.1
x-visibility:
extent: EXTERNAL
x-publicSDKSamples:
- language: C#
link: https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanCreate.aspx.cs
- language: JAVA
link: https://github.com/paypal/PayPal-Java-SDK/blob/master/rest-api-sample/src/main/java/com/paypal/api/sample/SubscriptionSample.java#L35
- language: Node
link: https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/create.js
- language: PHP
link: https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/CreatePlan.php
- language: Python
link: https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/create.py
x-codegen-request-body-name: plan
components:
schemas:
plan:
title: Plan
required:
- description
- name
- type
type: object
properties:
id:
maxLength: 128
type: string
description: The ID of the plan.
readOnly: true
name:
maxLength: 128
type: string
description: The plan name.
description:
maxLength: 127
type: string
description: The plan description. Maximum length is 127 single-byte
alphanumeric characters.
type:
maxLength: 20
type: string
description: The plan type. Indicates whether the payment definitions in the
plan have a fixed number of or infinite payment cycles. Value
is:FIXED. The plan has a fixed number of
payment cycles.INFINITE. The plan has
infinite, or 0, payment cycles.NO. PayPal does not automatically bill the
customer the outstanding balance.YES. PayPal
automatically bills the customer the outstanding balance.CONTINUE. The agreement remains active and
the failed payment amount is added to the outstanding balance. If
auto-billing is enabled, PayPal automatically bills the outstanding
balance in the next billing cycle.CANCEL
PayPal creates the agreement but sets its state to pending until the
initial payment clears. If the initial payment clears, the pending
agreement becomes active. If the initial payment fails, the pending
agreement is canceled.Note: You can use the `setup_fee` value as the initial amount to trigger the `initial_fail_amount_action`.default: CONTINUE enum: - CONTINUE - CANCEL accepted_payment_type: type: string description: The payment types that are accepted for this plan. Read-only and reserved for future use. readOnly: true char_set: type: string description: The character set for this plan. Read-only and reserved for future use. readOnly: true setup_fee: type: object allOf: - $ref: "#/components/schemas/currency" - type: object description: The currency and amount of the set-up fee for the agreement. This fee is the initial, non-recurring payment amount that is due immediately when the billing agreement is created. Can be used as the initial amount to trigger the `initial_fail_amount_action`. The default for the amount is `0`. description: The merchant preferences for a plan, which define how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails. x-visibility: extent: EXTERNAL link_description: title: Link Description required: - href - rel type: object properties: href: type: string description: The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call. x-visibility: extent: EXTERNAL rel: type: string description: The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml). x-visibility: extent: EXTERNAL method: type: string description: The HTTP method required to make the related call. enum: - GET - POST - PUT - DELETE - HEAD - CONNECT - OPTIONS - PATCH x-visibility: extent: EXTERNAL description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information. currency: title: Currency required: - currency - value type: object properties: currency: type: string description: The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/). value: type: string description: The value, which might be:
value parameter
defines the value to add. For more information, see 4.1.
add.
- value: remove
description: Removes the value at the target location. For the operation to
succeed, the target location must exist. For more information,
see 4.2.
remove.
- value: replace
description: Replaces the value at the target location with a new value. The
operation object must contain a value parameter
that defines the replacement value. For the operation to
succeed, the target location must exist. For more information,
see 4.3.
replace.
- value: move
description: Removes the value at a specified location and adds it to the target
location. The operation object must contain a from
parameter, which is a string that contains a JSON pointer value
that references the location in the target document from which
to move the value. For the operation to succeed, the
from location must exist. For more information, see
4.4.
move.
- value: copy
description: Copies the value at a specified location to the target location.
The operation object must contain a from parameter,
which is a string that contains a JSON pointer value that
references the location in the target document from which to
copy the value. For the operation to succeed, the
from location must exist. For more information, see
4.5.
copy.
- value: test
description: Tests that a value at the target location is equal to a specified
value. The operation object must contain a value
parameter that defines the value to compare to the target
location's value. For the operation to succeed, the target
location must be equal to the value value. For
test, equal indicates that the value at the target
location and the value that value defines are of
the same JSON type. The data type of the value determines how
equality is defined:| Type | Considered equal if both values |
|---|---|
| strings | Contain the same number of Unicode characters and their code points are byte-by-byte equal. |
| numbers | Are numerically equal. |
| arrays | Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules. |
| objects | Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules). |
literals (false,
true, and null) | Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant. |
remove operation does not
require a value.
from:
type: string
description: The JSON Pointer
to the target document location from which to move the value.
Required for the move operation.
description: The JSON patch object to apply partial updates to resources.
securitySchemes:
Oauth2:
type: oauth2
description: Oauth 2.0 authentication
flows:
clientCredentials:
tokenUrl: /api/oauth-proxy
scopes:
https://uri.paypal.com/services/subscriptions: Create and manage a plan
x-deprecated:
see: v1/billing/plans
since_version: "1.2"
x-errors:
- name: INTERNAL_SERVICE_ERROR
message: An internal service error has occurred.
description: Resend the request at another time. If this error continues,
contact [PayPal Merchant Technical
Support](https://developer.paypal.com/webapps/developer/support).
- name: REQUIRED_SCOPE_MISSING
message: Access token does not have required scope.
description: Use the scope required for this request type to get buyer consent.
- name: UNAUTHORIZED_ACCESS
message: You don't have permission to access this resource.
description: Pass a valid plan ID.
- name: VALIDATION_ERROR
message: Invalid request - see details.
description: A validation issue occurred with your request.
x-requestValidationIssues:
- name: RequiredFieldMissing
message: Required field missing.
- name: TMP_NAME_FIELD_MISSING
message: Field is mandatory. Limit of 127 characters.
- name: TMP_DESC_FIELD_MISSING
message: Field is mandatory. Limit of 127 characters.
- name: TMP_INVALID_PDS
message: Payment definitions are invalid. Valid parameters are REGULAR or
combination of TRIAL and REGULAR.
- name: TMP_INVALID_TYPE
message: Template type is either null or invalid. Valid parameters are UNLIMITED
or FIXED.
- name: QUERYPARAM_INVALID_PAGE_SIZE
message: Invalid Page size, valid value is positive number less than 21.
- name: INVALID_REGULAR_AMOUNT
message: Amount passed in regular payment definition should be more than zero.
- name: PD_INVALID_CURRENCY_OBJECT
message: Currency object of payment definition can't be null.
- name: QUERYPARAM_INVALID_TOTAL_REQUIRED
message: Invalid Total required, valid value are yes or no.
- name: TMP_INVALID_MPREF
message: Merchant preferences are mandatory.
- name: PD_INVALID_NAME
message: Field is mandatory. Limit of 127 characters.
- name: PD_INVALID_TYPE
message: Payment Definition type passed is either null/invalid. Valid values are
TRIAL or REGULAR.
- name: PD_INVALID_FREQ
message: Payment Definition Frequency type passed is either null/invalid. Valid
values are DAY, WEEK, MONTH or YEAR.
- name: PD_INVALID_FREQ_COUNT
message: Payment Definition Frequency count should be positive numeric.
- name: PD_INVALID_CYCLES
message: Number of Cycles should be positive numeric and less than 10000.
- name: PD_INVALID_AMT
message: Amount should a positive number greater than 0 with a maximum of 2
decimal places separated by '.', optional thousands separator ',', limited
to 7 digits before the decimal point.
- name: PD_INVALID_CMLIST
message: Charge Models within a payment definition should have distinct 'Types'.
- name: AMT_BLANK
message: Amount cannot be blank.
- name: CM_INVALID_TYPE
message: Charge Model type is invalid or null. Valid parameters are SHIPPING or TAX.
- name: CM_INVALID_AMOUNT
message: Charge Model amount should be non-negative number with a maximum of 2
decimal places separated by '.', optional thousands separator ',', limited
to 7 digits before the decimal point.
- name: CM_INVALID_ID
message: Charge Model id should not be null or blank.
- name: MP_INVALID_AUTOBILL
message: invalid autobill_amount type. Can be yes or no.
- name: MP_INVALID_INIT_FAIL_AMT_ACTION
message: Invalid init amount action. Valid values are CANCEL, CONTINUE.
- name: QUERYPARAM_INVALID_SORT_ORDER
message: Sort order is invalid, valid values are asc / desc.
- name: QUERYPARAM_INVALID_STATUS
message: Invalid status, valid values are CREATED, ACTIVE, INACTIVE.
- name: TEMPLATE_ID_INVALID
message: Incorrect Template Id.
- name: SET_UP_FEE
message: setup_fee is invalid/null.It should be positive number with max value
9999999.
- name: AUTO_BILL_AMT
message: Invalid autobill_amount type. Can be yes or no.
- name: FAIL_INIT_AMT_ACTION
message: Invalid fail_initamt_action. Can be continue or cancel.
- name: MAX_FAIL_ATTEMPTS
message: max_fail_attempts is invalid/null.It should be positive integer with
max value 999.
- name: INVALID_URL
message: Missing/Invalid URL entered.Max length is 2048.
- name: AUTO_BILL_AMT
message: Invalid autobill_amount type. Can be yes or no.
- name: INVALID_PLAN_CURRENCIES
message: All amounts with in a plan should have same currency.
- name: CHARGE_MODEL_ID_INVALID
message: Invalid Charge Model Id.
- name: PAYMENT_DEF_ID_INVALID
message: Invalid payment def Id.
- name: INVALID_INFINITE_PD_VALUE
message: If payment definition type is REGULAR, no_of_cycles can only be null or
0 for an UNLIMITED plan.
- name: INVALID_FIXED_PD_VALUE
message: no_of_cycles can't be null or 0 for a FIXED plan.
- name: INVALID_TRIAL_CYCLE_VALUE
message: For TRIAL payment definition, number of cycles can't be null or 0.
- name: INVALID_PD_SPECIFIED
message: You can't create template with only TRIAL as payment definition.
- name: CANT_ACTIVATE_ACTIVE_TEMPLATE
message: You can't activate an active template.
- name: CANT_MODIFY_DELETED_TEMPLATE
message: Invalid template Id.
- name: CANT_DEACTIVATE_INACTIVE_TEMPLATE
message: You can't deactivate an inactive template.
- name: CAN_UPDATE_TEMPLATE_ONLY_IN_CREATED_STATE
message: Updation of a template only allowed in CREATED state.
- name: REMOVE_OPERATION_NOT_SUPPORTED
message: Remove operation not supported now.
- name: ADD_OPERATION_NOT_SUPPORTED
message: Add operation not supported now.
- name: INVALID_OPERATION
message: Invalid Operation nome. Can be add, remove or replace.
- name: INVALID_PATCH_PATH
message: Invalid Path provided.
- name: UNWANTED_FIELD_MESSAGE
message: patch is not supported for this field.
- name: INVALID_STATE
message: Invalid state entered.Valid values are created/deleted/inactive/active.
- name: INVALID_STATE_CHANGE_REQUEST
message: Requested state change is invalid.
- name: TEMPLATE_ALREADY_IN_GIVEN_STATE
message: Plan already in same state.
- name: FREQ_MORE_THAN_YEAR
message: Frequency more than year is not supported.
- name: TEMPLATE_ALREADY_IN_GIVEN_STATE
message: Plan already in same state.
- name: MustNotBeBlank
message: Must not be blank.
- name: InvalidCurrencyCode
message: Currency code must be 3-character ISO 4217 value (upper case).
- name: InvalidPositiveNumber
message: Must be a positive integer.
- name: InvalidFormatUrl
message: Invalid URL.
- name: InvalidFormatCurrencyAmount
message: Currency amount must be non-negative number, may optionally contain
exactly 2 decimal places separated by '.', optional thousands separator
',', limited to 7 digits before the decimal point.
- name: InvalidNumeric
message: Must be numeric.
- name: InvalidAlphanumeric
message: Must be alphanumeric.
- name: InvalidAlphaNumPlus
message: "Must contain only these characters: a-z, A-Z, 0-9, punctuation(.,#-'),
and embedded spaces."
- name: InvalidDateTimeFormat
message: Must be a date_time string of form yyyy-mm-ddThh:mm:ss(.sss)?Z.
- name: InvalidDateTime
message: The date_time, although formatted properly, does not represent a valid
date_time.
- name: InvalidQueryParams
message: Invalid to specify both start_id and start_index query params.
- name: ReadonlyField
message: Not valid to specify this field in a request.
- name: InvalidIntegerFormat
message: Invalid value.
- name: FractionDigitsNotAllowed
message: Fraction digits are not allowed with this currency.