| Attribute or object | Operations |
|---|---|
description | replace |
payment_preferences.auto_bill_outstanding | replace |
taxes.percentage | replace |
payment_preferences.payment_failure_threshold | replace |
payment_preferences.setup_fee | replace |
payment_preferences.setup_fee_failure_action | replace |
name | replace |
1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).
minimum: 0
maximum: 999
default: 1
required:
- frequency
- tenure_type
- sequence
error_409:
type: object
title: Resource Conflict Error
description: The server has detected a conflict while processing this request.
properties:
name:
type: string
enum:
- RESOURCE_CONFLICT
message:
type: string
enum:
- The server has detected a conflict while processing this request.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
'403':
properties:
details:
type: array
items:
anyOf:
- title: PERMISSION_DENIED
properties:
issue:
type: string
enum:
- PERMISSION_DENIED
description:
type: string
enum:
- You do not have permission to access or perform operations on this resource.
payment_preferences:
title: Payment Preferences
description: The payment preferences for a subscription.
type: object
properties:
auto_bill_outstanding:
type: boolean
description: Indicates whether to automatically bill the outstanding amount in the next billing cycle.
default: true
setup_fee:
description: The initial set-up fee for the service.
$ref: '#/components/schemas/money'
setup_fee_failure_action:
type: string
description: The action to take on the subscription if the initial payment for the setup fails.
minLength: 1
maxLength: 24
pattern: ^[A-Z_]+$
default: CANCEL
enum:
- CONTINUE
- CANCEL
payment_failure_threshold:
type: integer
description: The maximum number of payment failures before a subscription is suspended. For example, if `payment_failure_threshold` is `2`, the subscription automatically updates to the `SUSPEND` state if two consecutive payments fail.
minimum: 0
maximum: 999
default: 0
link_description:
type: object
title: Link Description
description: The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.
required:
- href
- rel
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.
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).
method:
type: string
description: The HTTP method required to make the related call.
enum:
- GET
- POST
- PUT
- DELETE
- HEAD
- CONNECT
- OPTIONS
- PATCH
plans.patch-422:
properties:
details:
type: array
items:
anyOf:
- title: USER_ACCOUNT_CLOSED
properties:
issue:
type: string
enum:
- USER_ACCOUNT_CLOSED
description:
type: string
enum:
- User account locked or closed.
- title: PLAN_STATUS_INACTIVE
properties:
issue:
type: string
enum:
- PLAN_STATUS_INACTIVE
description:
type: string
enum:
- Status update is the only patchable filed on an inactive plan.
patch:
type: object
title: Patch
description: The JSON patch object to apply partial updates to resources.
properties:
op:
type: string
description: The operation.
enum:
- add
- remove
- replace
- move
- copy
- test
path:
type: string
description: The JSON Pointer to the target document location at which to complete the operation.
value:
title: Patch Value
description: The value to apply. The 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.
required:
- op
error_403:
type: object
title: Not Authorized Error
description: 'The client is not authorized to access this resource, although it may have valid credentials. '
properties:
name:
type: string
enum:
- NOT_AUTHORIZED
message:
type: string
enum:
- Authorization failed due to insufficient permissions.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
error_422:
type: object
title: Unprocessable Entity Error
description: The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.
properties:
name:
type: string
enum:
- UNPROCESSABLE_ENTITY
message:
type: string
enum:
- The requested action could not be performed, semantically incorrect, or failed business validation.
details:
type: array
items:
$ref: '#/components/schemas/error_details'
debug_id:
type: string
description: The PayPal internal ID. Used for correlation purposes.
links:
description: An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).
type: array
minItems: 0
maxItems: 10000
items:
$ref: '#/components/schemas/error_link_description'
plans.update-pricing-schemes-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- title: MISSING_REQUIRED_PARAMETER
properties:
issue:
type: string
enum:
- MISSING_REQUIRED_PARAMETER
description:
type: string
enum:
- A required field is missing.
update_pricing_scheme_request:
title: Update Pricing Scheme
description: The update pricing scheme request details.
type: object
properties:
billing_cycle_sequence:
type: integer
description: The billing cycle sequence.
minimum: 1
maximum: 99
pricing_scheme:
$ref: '#/components/schemas/pricing_scheme'
required:
- billing_cycle_sequence
- pricing_scheme
error_details:
title: Error Details
type: object
description: The error details. Required for client-side `4XX` errors.
properties:
field:
type: string
description: The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.
value:
type: string
description: The value of the field that caused the error.
location:
$ref: '#/components/schemas/error_location'
issue:
type: string
description: The unique, fine-grained application-level error code.
description:
type: string
description: The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.
required:
- issue
error_link_description:
title: Link Description
description: The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.
type: object
required:
- href
- rel
properties:
href:
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.
type: string
minLength: 0
maxLength: 20000
pattern: ^.*$
rel:
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).
type: string
minLength: 0
maxLength: 100
pattern: ^.*$
method:
description: The HTTP method required to make the related call.
type: string
minLength: 3
maxLength: 6
pattern: ^[A-Z]*$
enum:
- GET
- POST
- PUT
- DELETE
- PATCH
plans.deactivate-422:
properties:
details:
type: array
items:
anyOf:
- title: USER_ACCOUNT_CLOSED
properties:
issue:
type: string
enum:
- USER_ACCOUNT_CLOSED
description:
type: string
enum:
- User account locked or closed.
- title: PLAN_STATUS_INVALID
properties:
issue:
type: string
enum:
- PLAN_STATUS_INVALID
description:
type: string
enum:
- Invalid plan status for deactivate action; plan status should be active.
plan:
title: Plan
description: The plan details.
type: object
properties:
id:
type: string
description: The unique PayPal-generated ID for the plan.
minLength: 3
maxLength: 50
readOnly: true
product_id:
type: string
description: The ID for the product.
minLength: 6
maxLength: 50
name:
type: string
description: The plan name.
minLength: 1
maxLength: 127
status:
type: string
description: The plan status.
minLength: 1
maxLength: 24
pattern: ^[A-Z_]+$
enum:
- CREATED
- INACTIVE
- ACTIVE
description:
type: string
description: The detailed description of the plan.
minLength: 1
maxLength: 127
billing_cycles:
type: array
description: An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.
minItems: 1
maxItems: 12
items:
$ref: '#/components/schemas/billing_cycle'
payment_preferences:
$ref: '#/components/schemas/payment_preferences'
taxes:
$ref: '#/components/schemas/taxes'
quantity_supported:
type: boolean
description: Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.
default: false
create_time:
description: The date and time when the plan was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
$ref: '#/components/schemas/date_time'
update_time:
description: The date and time when the plan was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
$ref: '#/components/schemas/date_time'
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
minItems: 1
maxItems: 10
items:
$ref: '#/components/schemas/link_description'
readOnly: true
error_default:
description: The default error response.
oneOf:
- $ref: '#/components/schemas/error_400'
- $ref: '#/components/schemas/error_401'
- $ref: '#/components/schemas/error_403'
- $ref: '#/components/schemas/error_404'
- $ref: '#/components/schemas/error_409'
- $ref: '#/components/schemas/error_415'
- $ref: '#/components/schemas/error_422'
- $ref: '#/components/schemas/error_500'
- $ref: '#/components/schemas/error_503'
'400':
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
error_location:
type: string
description: The location of the field that caused the error. Value is `body`, `path`, or `query`.
enum:
- body
- path
- query
default: body
plan_collection:
title: Plan Collection
description: The list of plans with details.
type: object
properties:
plans:
type: array
minItems: 0
maxItems: 32767
description: An array of plans.
items:
$ref: '#/components/schemas/plan'
total_items:
type: integer
description: The total number of items.
minimum: 0
maximum: 500000000
total_pages:
type: integer
description: The total number of pages.
minimum: 0
maximum: 100000000
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
minItems: 1
maxItems: 10
items:
readOnly: true
$ref: '#/components/schemas/link_description'
patch_request:
type: array
title: Patch Request
description: An array of JSON patch objects to apply partial updates to resources.
items:
$ref: '#/components/schemas/patch'
money:
type: object
title: Money
description: The currency and amount for a financial transaction, such as a balance or payment due.
properties:
currency_code:
$ref: '#/components/schemas/currency_code'
value:
type: string
description: The value, which might be:Note: The regular expression provides guidance but does not reject all invalid dates.format: ppaas_date_time_v3 minLength: 20 maxLength: 64 pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$ frequency: title: Billing Cycle Frequency description: The frequency of the billing cycle. type: object properties: interval_unit: type: string description: The interval at which the subscription is charged or billed. minLength: 1 maxLength: 24 pattern: ^[A-Z_]+$ enum: - DAY - WEEK - MONTH - YEAR interval_count: type: integer description: The number of intervals after which a subscriber is billed. For example, if the `interval_unit` is `DAY` with an `interval_count` of `2`, the subscription is billed once every two days. The following table lists the maximum allowed values for the `interval_count` for each `interval_unit`:
Interval unit | Maximum interval count |
|---|---|
DAY | 365 |
WEEK | 52 |
MONTH | 12 |
YEAR | 1 |
return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource.