| 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 |
ACTIVE or SUSPENDED status. You can override plan level default attributes by providing customised values for plan path in the patch request.| Attribute or object | Operations |
|---|---|
billing_info.outstanding_balance | replace |
custom_id | add,replace |
plan.billing_cycles[@sequence==n]. | add,replace |
plan.billing_cycles[@sequence==n]. | replace |
plan.billing_cycles[@sequence==n]. | replace |
plan.payment_preferences. | replace |
plan.payment_preferences. | replace |
plan.taxes.inclusive | add,replace |
plan.taxes.percentage | add,replace |
shipping_amount | add,replace |
start_time | replace |
subscriber.shipping_address | add,replace |
subscriber.payment_source (for subscriptions funded | replace |
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})$" pricing_scheme: title: Pricing Scheme description: The pricing scheme details. type: object properties: version: type: integer description: The version of the pricing scheme. minimum: 0 maximum: 999 readOnly: true fixed_price: description: The fixed amount to charge for the subscription. The changes to fixed amount are applicable to both existing and future subscriptions. For existing subscriptions, payments within 10 days of price change are not affected. "$ref": "#/components/schemas/money" pricing_model: type: string description: The pricing model for tiered plan. The `tiers` parameter is required. minLength: 1 maxLength: 24 pattern: "^[A-Z_]+$" enum: - VOLUME - TIERED tiers: type: array description: An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified. minItems: 1 maxItems: 32 items: "$ref": "#/components/schemas/pricing_tier" create_time: description: The date and time when this pricing scheme 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 this pricing scheme 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" 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 |
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
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
percentage:
type: string
description: The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`.
format: ppaas_common_percentage_v2
pattern: "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$"
taxes:
title: Taxes
description: The tax details.
type: object
properties:
percentage:
description: The tax percentage on the billing amount.
"$ref": "#/components/schemas/percentage"
inclusive:
type: boolean
description: Indicates whether the tax was already included in the billing amount.
default: true
required:
- percentage
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
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
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"
plan_request_POST:
title: Create Plan Request
description: The create plan request details.
type: object
properties:
product_id:
type: string
description: The ID of the product created through Catalog Products API.
minLength: 6
maxLength: 50
name:
type: string
description: The plan name.
minLength: 1
maxLength: 127
status:
type: string
description: The initial state of the plan. Allowed input values are CREATED and ACTIVE.
minLength: 1
maxLength: 24
pattern: "^[A-Z_]+$"
default: ACTIVE
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
required:
- name
- billing_cycles
- payment_preferences
- product_id
plans.create-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- The value of a field does not conform to the expected format.
- 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.
- title: INVALID_STRING_MIN_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MIN_LENGTH
description:
type: string
enum:
- The value of a field is too short.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
- title: INVALID_INTEGER_MIN_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MIN_VALUE
description:
type: string
enum:
- The integer value of a field is too small.
- title: INVALID_INTEGER_MAX_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MAX_VALUE
description:
type: string
enum:
- The integer value of a field is too large.
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
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"
plans.patch-400:
properties:
details:
type: array
items:
anyOf:
- title: UNSUPPORTED_PATCH_OPERATION
properties:
issue:
type: string
enum:
- UNSUPPORTED_PATCH_OPERATION
description:
type: string
enum:
- The specified patch operation not supported for this field.
- title: INVALID_PATCH_PATH
properties:
issue:
type: string
enum:
- INVALID_PATCH_PATH
description:
type: string
enum:
- The specified field cannot be patched.
- title: INVALID_PATCH_PATH
properties:
issue:
type: string
enum:
- INVALID_PATCH_PATH
description:
type: string
enum:
- Multiple operations on the same field are not allowed.
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- The value of a field does not conform to the expected format.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The field is not eligible for '$value' patch operation.
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.
plans.activate-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 activate action; plan status should be either created or inactive.
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.
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
update_pricing_schemes_list_request:
title: Update Pricing Scheme Request
description: The update pricing scheme request details.
type: object
properties:
pricing_schemes:
type: array
description: An array of pricing schemes.
minItems: 1
maxItems: 99
items:
"$ref": "#/components/schemas/update_pricing_scheme_request"
required:
- pricing_schemes
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.
plans.update-pricing-schemes-422:
properties:
details:
type: array
items:
anyOf:
- title: CURRENCY_MISMATCH
properties:
issue:
type: string
enum:
- CURRENCY_MISMATCH
description:
type: string
enum:
- The currency code is different from the plan's currency code.
- title: INVALID_BILLING_CYCLE_SEQUENCE
properties:
issue:
type: string
enum:
- INVALID_BILLING_CYCLE_SEQUENCE
description:
type: string
enum:
- The provided billing cycle sequence is not available.
- title: INVALID_PRICING_SCHEME
properties:
issue:
type: string
enum:
- INVALID_PRICING_SCHEME
description:
type: string
enum:
- The new pricing scheme should be of the same type as that of the old one.
- title: INVALID_PRICING_TIER_AMOUNT
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_AMOUNT
description:
type: string
enum:
- Free tiers are not supported.
- title: MISSING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- MISSING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- Tier(s) are missing for some quantities.
- title: OVERLAPPING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- OVERLAPPING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- The specified quantity overlaps with multiple pricing tiers.
- title: INVALID_PRICING_MODEL
properties:
issue:
type: string
enum:
- INVALID_PRICING_MODEL
description:
type: string
enum:
- The specified pricing model is not supported for trial billing cycle.
- title: FIXED_PRICE_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- FIXED_PRICE_NOT_SUPPORTED
description:
type: string
enum:
- Fixed price is not supported for tiered pricing schemes.
- title: INVALID_PRICING_TIER_QUANTITY
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_QUANTITY
description:
type: string
enum:
- Tier starting quantity must be less than ending quantity.
- title: PRICING_SCHEME_UPDATE_NOT_ALLOWED
properties:
issue:
type: string
enum:
- PRICING_SCHEME_UPDATE_NOT_ALLOWED
description:
type: string
enum:
- Pricing scheme update is not allowed for the plan.
email:
type: string
description: The internationalized email address.Note: Up to 64 characters are allowed before and 255 characters are allowed after theformat: merchant_common_email_address_v2 maxLength: 254 pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]) account_id: type: string title: PayPal Account Identifier description: The account identifier for a PayPal account. format: ppaas_payer_id_v3 minLength: 13 maxLength: 13 pattern: "^[2-9A-HJ-NP-Z]{13}$" payer_base: type: object title: Payer Base description: The customer who approves and pays for the order. The customer is also known as the payer. properties: email_address: description: The email address of the payer. "$ref": "#/components/schemas/email" payer_id: description: The PayPal-assigned ID for the payer. readOnly: true "$ref": "#/components/schemas/account_id" name: type: object title: Name description: The name of the party. properties: prefix: type: string description: The prefix, or title, to the party's name. maxLength: 140 given_name: type: string description: When the party is a person, the party's given, or first, name. maxLength: 140 surname: type: string description: When the party is a person, the party's surname or family name. Also known as the last name. Required when the party is a person. Use also to store multiple surnames including the matronymic, or mother's, surname. maxLength: 140 middle_name: type: string description: When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name. maxLength: 140 suffix: type: string description: The suffix for the party's name. maxLength: 140 alternate_full_name: type: string description: DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business. maxLength: 300 full_name: type: string description: When the party is a person, the party's full name. maxLength: 300 phone_type: type: string title: Phone Type description: The phone type. enum: - FAX - HOME - MOBILE - OTHER - PAGER phone: type: object title: Phone description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). properties: country_code: type: string description: The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). minLength: 1 maxLength: 3 pattern: "^[0-9]{1,3}?$" national_number: type: string description: The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). The combined length of the country calling code (CC) and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). minLength: 1 maxLength: 14 pattern: "^[0-9]{1,14}?$" extension_number: type: string description: The extension number. minLength: 1 maxLength: 15 pattern: "^[0-9]{1,15}?$" required: - country_code - national_number phone_with_type: type: object title: Phone With Type description: The phone information. properties: phone_type: "$ref": "#/components/schemas/phone_type" phone_number: description: The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). Supports only the `national_number` property. "$ref": "#/components/schemas/phone" required: - phone_number date_no_time: type: string description: The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard `date_time` type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years. format: ppaas_date_notime_v2 minLength: 10 maxLength: 10 pattern: "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$" tax_info: type: object description: The tax ID of the customer. The customer is also known as the payer. Both `tax_id` and `tax_id_type` are required. title: Tax Information properties: tax_id: type: string description: The customer's tax ID value. maxLength: 14 tax_id_type: type: string description: The customer's tax ID type. enum: - BR_CPF - BR_CNPJ required: - tax_id - tax_id_type country_code: type: string description: The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) that identifies the country or region.@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Note: The country code for Great Britain isformat: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: "^([A-Z]{2}|C2)$" address_portable: type: object title: Portable Postal Address (Medium-Grained) description: 'The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).' properties: address_line_1: type: string description: The first line of the address. For example, number or street. For example, `173 Drury Lane`. Required for data entry and compliance and risk checks. Must contain the full address. maxLength: 300 address_line_2: type: string description: The second line of the address. For example, suite or apartment number. maxLength: 300 address_line_3: type: string description: The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as `next to Walmart`, or a landmark in an Indian address. maxLength: 100 admin_area_4: type: string description: The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is:GBand notUKas used in the top-level domain names for that country. Use the `C2` country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
Craven House.
maxLength: 100
sub_building:
type: string
description: The first-order entity below a named building or location that represents the sub-premises. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
maxLength: 100
required:
- country_code
payer:
type: object
title: Customer
description: The customer who approves and pays for the order. The customer is also known as the payer.
format: payer_v1
allOf:
- "$ref": "#/components/schemas/payer_base"
- properties:
name:
description: The name of the payer. Supports only the `given_name` and `surname` properties.
"$ref": "#/components/schemas/name"
phone:
description: The phone number of the customer. Available only when you enable the **Contact Telephone Number** option in the **Profile & Settings** for the merchant's PayPal account. The `phone.phone_number` supports only `national_number`.
"$ref": "#/components/schemas/phone_with_type"
birth_date:
description: The birth date of the payer in `YYYY-MM-DD` format.
"$ref": "#/components/schemas/date_no_time"
tax_info:
description: The tax information of the payer. Required only for Brazilian payer's. Both `tax_id` and `tax_id_type` are required.
"$ref": "#/components/schemas/tax_info"
address:
description: The address of the payer. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties. Also referred to as the billing address of the customer.
"$ref": "#/components/schemas/address_portable"
shipping_detail:
type: object
description: The shipping details.
title: Shipping Details
properties:
name:
description: The name of the person to whom to ship the items. Supports only the `full_name` property.
"$ref": "#/components/schemas/name"
type:
description: The method by which the payer wants to get their items from the payee e.g shipping, in-person pickup. Either type or options but not both may be present.
type: string
minLength: 1
maxLength: 255
pattern: "^[0-9A-Z_]+$"
enum:
- SHIPPING
- PICKUP_IN_PERSON
address:
description: The address of the person to whom to ship the items. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties.
"$ref": "#/components/schemas/address_portable"
date_year_month:
type: string
description: The year and month, in ISO-8601 `YYYY-MM` date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
minLength: 7
maxLength: 7
pattern: "^[0-9]{4}-(0[1-9]|1[0-2])$"
card_brand:
type: string
title: Card Brand
description: The card network or brand. Applies to credit, debit, gift, and payment cards.
minLength: 1
maxLength: 255
pattern: "^[A-Z_]+$"
enum:
- VISA
- MASTERCARD
- DISCOVER
- AMEX
- SOLO
- JCB
- STAR
- DELTA
- SWITCH
- MAESTRO
- CB_NATIONALE
- CONFIGOGA
- CONFIDIS
- ELECTRON
- CETELEM
- CHINA_UNION_PAY
card:
type: object
title: Card
description: The payment card to use to fund a payment. Can be a credit or debit card.
properties:
id:
type: string
description: The PayPal-generated ID for the card.
readOnly: true
name:
type: string
description: The card holder's name as it appears on the card.
maxLength: 300
number:
type: string
description: The primary account number (PAN) for the payment card.
minLength: 13
maxLength: 19
expiry:
description: The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).
"$ref": "#/components/schemas/date_year_month"
security_code:
type: string
description: The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when `payment_initiator=MERCHANT`.
pattern: "[0-9]{3,4}"
last_digits:
type: string
description: The last digits of the payment card.
pattern: "[0-9]{2,}"
readOnly: true
card_type:
description: The card brand or network. Typically used in the response.
readOnly: true
"$ref": "#/components/schemas/card_brand"
billing_address:
description: The billing address for this card. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties.
"$ref": "#/components/schemas/address_portable"
required:
- number
- expiry
payment_source:
type: object
title: Payment Source
description: The payment source definition. To be eligible to create subscription using debit or credit card, you will need to sign up here (https://www.paypal.com/bizsignup/entry/product/ppcp). Please note, its available only for non-3DS cards and for merchants in US and AU regions.
properties:
card:
"$ref": "#/components/schemas/card"
subscriber_request:
title: Subscriber Request Information
description: The subscriber request information .
type: object
allOf:
- "$ref": "#/components/schemas/payer"
- properties:
shipping_address:
"$ref": "#/components/schemas/shipping_detail"
payment_source:
"$ref": "#/components/schemas/payment_source"
language:
type: string
description: The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/).
format: ppaas_common_language_v3
maxLength: 10
minLength: 2
pattern: "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$"
payee_payment_method_preference:
type: string
description: The merchant-preferred payment methods.
minLength: 1
maxLength: 255
pattern: "^[0-9A-Z_]+$"
default: UNRESTRICTED
enum:
- UNRESTRICTED
- IMMEDIATE_PAYMENT_REQUIRED
payment_method:
type: object
description: The customer and merchant payment preferences.
title: Payment Method
properties:
payer_selected:
type: string
description: The customer-selected payment method on the merchant site.
minLength: 1
pattern: "^[0-9A-Z_]+$"
default: PAYPAL
payee_preferred:
"$ref": "#/components/schemas/payee_payment_method_preference"
standard_entry_class_code:
type: string
description: NACHA (the regulatory body governing the ACH network) requires that API callers (merchants, partners) obtain the consumer’s explicit authorization before initiating a transaction. To stay compliant, you’ll need to make sure that you retain a compliant authorization for each transaction that you originate to the ACH Network using this API. ACH transactions are categorized (using SEC codes) by how you capture authorization from the Receiver (the person whose bank account is being debited or credited). PayPal supports the following SEC codes.
default: WEB
minLength: 3
maxLength: 255
enum:
- TEL
- WEB
- CCD
- PPD
application_context:
title: Application Context
description: The application context, which customizes the payer experience during the subscription approval process with PayPal.
type: object
properties:
brand_name:
type: string
description: The label that overrides the business name in the PayPal account on the PayPal site.
minLength: 1
maxLength: 127
locale:
description: The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, `da-DK`, `he-IL`, `id-ID`, `ja-JP`, `no-NO`, `pt-BR`, `ru-RU`, `sv-SE`, `th-TH`, `zh-CN`, `zh-HK`, or `zh-TW`.
"$ref": "#/components/schemas/language"
shipping_preference:
type: string
description: The location from which the shipping address is derived.
minLength: 1
maxLength: 24
pattern: "^[A-Z_]+$"
default: GET_FROM_FILE
enum:
- GET_FROM_FILE
- NO_SHIPPING
- SET_PROVIDED_ADDRESS
user_action:
type: string
description: Configures the label name to `Continue` or `Subscribe Now` for subscription consent experience.
minLength: 1
maxLength: 24
pattern: "^[A-Z_]+$"
default: SUBSCRIBE_NOW
enum:
- CONTINUE
- SUBSCRIBE_NOW
payment_method:
description: The customer and merchant payment preferences. Currently only PAYPAL payment method is supported.
"$ref": "#/components/schemas/payment_method"
return_url:
type: string
format: uri
description: The URL where the customer is redirected after the customer approves the payment.
minLength: 10
maxLength: 4000
cancel_url:
type: string
format: uri
description: The URL where the customer is redirected after the customer cancels the payment.
minLength: 10
maxLength: 4000
required:
- return_url
- cancel_url
billing_cycle_override:
title: Billing Cycle Override
description: The billing cycle details to override at subscription level. The subscription billing cycle definition has to adhere to the plan billing cycle definition.
type: object
properties:
pricing_scheme:
description: The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.
"$ref": "#/components/schemas/pricing_scheme"
sequence:
type: integer
description: The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a `sequence` of `1` while a regular billing cycle has a `sequence` of `2`, so that trial cycle runs before the regular cycle.
minimum: 1
maximum: 99
total_cycles:
type: integer
description: The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 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
required:
- sequence
payment_preferences_override:
title: Payment Preferences Override
description: The payment preferences to override at subscription level.
type: object
properties:
auto_bill_outstanding:
type: boolean
description: Indicates whether to automatically bill the outstanding amount in the next billing cycle.
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_]+$"
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
taxes_override:
title: Taxes Override
description: The tax details.
type: object
properties:
percentage:
description: The tax percentage on the billing amount.
"$ref": "#/components/schemas/percentage"
inclusive:
type: boolean
description: Indicates whether the tax was already included in the billing amount.
plan_override:
title: Plan Override
description: An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object.
type: object
properties:
billing_cycles:
type: array
description: An array of billing cycles for trial billing and regular billing. The subscription billing cycle definition has to adhere to the plan billing cycle definition.
minItems: 1
maxItems: 12
items:
"$ref": "#/components/schemas/billing_cycle_override"
payment_preferences:
"$ref": "#/components/schemas/payment_preferences_override"
taxes:
"$ref": "#/components/schemas/taxes_override"
subscription_request_post:
title: Create Subscription Request
description: The create subscription request details.
type: object
properties:
plan_id:
type: string
description: The ID of the plan.
minLength: 3
maxLength: 50
start_time:
description: The date and time when the subscription started, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
default: Current time
"$ref": "#/components/schemas/date_time"
quantity:
type: string
description: The quantity of the product in the subscription.
pattern: "^([0-9]+|([0-9]+)?[.][0-9]+)$"
minLength: 1
maxLength: 32
shipping_amount:
description: The shipping charges.
"$ref": "#/components/schemas/money"
subscriber:
"$ref": "#/components/schemas/subscriber_request"
auto_renewal:
type: boolean
description: DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.
default: false
deprecated: true
application_context:
"$ref": "#/components/schemas/application_context"
custom_id:
type: string
description: The custom id for the subscription. Can be invoice id.
minLength: 1
maxLength: 127
pattern: "^[\\x20-\\x7E]+"
plan:
description: An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object.
"$ref": "#/components/schemas/plan_override"
required:
- plan_id
subscription_status:
title: Subscription Status
description: The subscription status details.
type: object
properties:
status:
type: string
description: The status of the subscription.
minLength: 1
maxLength: 24
pattern: "^[A-Z_]+$"
enum:
- APPROVAL_PENDING
- APPROVED
- ACTIVE
- SUSPENDED
- CANCELLED
- EXPIRED
status_change_note:
type: string
description: The reason or notes for the status of the subscription.
minLength: 1
maxLength: 128
status_update_time:
readOnly: true
"$ref": "#/components/schemas/date_time"
liability_shift:
type: string
minLength: 1
maxLength: 255
pattern: "^[0-9A-Z_]+$"
description: Liability shift indicator. The outcome of the issuer's authentication.
enum:
- 'YES'
- 'NO'
- POSSIBLE
- UNKNOWN
pares_status:
type: string
minLength: 1
maxLength: 255
pattern: "^[0-9A-Z_]+$"
description: Transactions status result identifier. The outcome of the issuer's authentication.
enum:
- Y
- N
- U
- A
- C
- R
- D
- I
enrolled:
type: string
minLength: 1
maxLength: 255
pattern: "^[0-9A-Z_]+$"
description: Status of Authentication eligibility.
enum:
- Y
- N
- U
- B
three_d_secure_authentication_response:
type: object
title: The 3D Secure Authentication Response
description: Results of 3D Secure Authentication.
properties:
authentication_status:
description: The outcome of the issuer's authentication.
"$ref": "#/components/schemas/pares_status"
enrollment_status:
description: Status of authentication eligibility.
"$ref": "#/components/schemas/enrolled"
authentication_response:
type: object
title: Authentication Response
description: Results of Authentication such as 3D Secure.
properties:
liability_shift:
"$ref": "#/components/schemas/liability_shift"
three_d_secure:
"$ref": "#/components/schemas/three_d_secure_authentication_response"
card_response:
type: object
title: Card Response
description: The payment card to use to fund a payment. Card can be a credit or debit card.
properties:
last_digits:
type: string
description: The last digits of the payment card.
pattern: "[0-9]{2,}"
readOnly: true
brand:
description: The card brand or network. Typically used in the response.
readOnly: true
"$ref": "#/components/schemas/card_brand"
type:
type: string
description: The payment card type.
readOnly: true
enum:
- CREDIT
- DEBIT
- PREPAID
- UNKNOWN
authentication_result:
"$ref": "#/components/schemas/authentication_response"
card_response_with_billing_address:
type: object
title: Card Response with billing address and name
description: The payment card used to fund the payment. Card can be a credit or debit card.
allOf:
- "$ref": "#/components/schemas/card_response"
- properties:
name:
type: string
description: The card holder's name as it appears on the card.
minLength: 2
maxLength: 300
billing_address:
"$ref": "#/components/schemas/address_portable"
description: The billing address for this card. Supports only the `address_line_1`, `address_line_2`, `admin_area_1`, `admin_area_2`, `postal_code`, and `country_code` properties.
expiry:
description: The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).
"$ref": "#/components/schemas/date_year_month"
currency_code:
description: Currency code of the given instrument
"$ref": "#/components/schemas/currency_code"
payment_source_response:
type: object
title: Payment Source Response
description: The payment source used to fund the payment.
properties:
card:
"$ref": "#/components/schemas/card_response_with_billing_address"
subscriber:
title: Subscriber Response Information
description: The subscriber response information.
type: object
allOf:
- "$ref": "#/components/schemas/payer"
- properties:
shipping_address:
"$ref": "#/components/schemas/shipping_detail"
payment_source:
"$ref": "#/components/schemas/payment_source_response"
cycle_execution:
title: Billing Cycle Execution Details
description: The regular and trial execution details for a billing cycle.
type: object
properties:
tenure_type:
type: string
description: The type of the billing cycle.
minLength: 1
maxLength: 24
pattern: "^[A-Z_]+$"
readOnly: true
enum:
- REGULAR
- TRIAL
sequence:
type: integer
description: The order in which to run this cycle among other billing cycles.
minimum: 0
maximum: 99
cycles_completed:
type: integer
description: The number of billing cycles that have completed.
minimum: 0
maximum: 9999
readOnly: true
cycles_remaining:
type: integer
description: For a finite billing cycle, cycles_remaining is the number of remaining cycles. For an infinite billing cycle, cycles_remaining is set as 0.
minimum: 0
maximum: 9999
readOnly: true
current_pricing_scheme_version:
type: integer
description: The active pricing scheme version for the billing cycle.
minimum: 1
maximum: 99
readOnly: true
total_cycles:
type: integer
description: The number of times this billing cycle gets executed. Trial billing cycles can only be executed a finite number of times (value between 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
readOnly: true
required:
- tenure_type
- sequence
- cycles_completed
last_payment_details:
title: Last Payment Details
description: The details for the last payment.
type: object
allOf:
- properties:
amount:
description: The last payment amount.
readOnly: true
"$ref": "#/components/schemas/money"
time:
description: The date and time when the last payment was made, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
"$ref": "#/components/schemas/date_time"
required:
- amount
- time
failed_payment_details:
title: Failed Payment Details
description: The details for the failed payment of the subscription.
type: object
properties:
amount:
description: The failed payment amount.
readOnly: true
"$ref": "#/components/schemas/money"
time:
description: The date and time when the failed payment was made, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
"$ref": "#/components/schemas/date_time"
reason_code:
type: string
description: The reason code for the payment failure.
minLength: 1
maxLength: 120
pattern: "^[A-Z_]+$"
readOnly: true
enum:
- PAYMENT_DENIED
- INTERNAL_SERVER_ERROR
- PAYEE_ACCOUNT_RESTRICTED
- PAYER_ACCOUNT_RESTRICTED
- PAYER_CANNOT_PAY
- SENDING_LIMIT_EXCEEDED
- TRANSACTION_RECEIVING_LIMIT_EXCEEDED
- CURRENCY_MISMATCH
next_payment_retry_time:
description: The time when the retry attempt for the failed payment occurs, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
"$ref": "#/components/schemas/date_time"
required:
- amount
- time
subscription_billing_info:
title: Subscription Billing Information
description: The billing details for the subscription. If the subscription was or is active, these fields are populated.
type: object
properties:
outstanding_balance:
description: The total pending bill amount, to be paid by the subscriber.
"$ref": "#/components/schemas/money"
cycle_executions:
type: array
description: The trial and regular billing executions.
minItems: 0
maxItems: 3
items:
"$ref": "#/components/schemas/cycle_execution"
readOnly: true
last_payment:
readOnly: true
description: The details for the last payment of the subscription.
"$ref": "#/components/schemas/last_payment_details"
next_billing_time:
description: The next date and time for billing this subscription, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
"$ref": "#/components/schemas/date_time"
final_payment_time:
description: The date and time when the final billing cycle occurs, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).
readOnly: true
"$ref": "#/components/schemas/date_time"
failed_payments_count:
type: integer
description: The number of consecutive payment failures. Resets to `0` after a successful payment. If this reaches the `payment_failure_threshold` value, the subscription updates to the `SUSPENDED` state.
minimum: 0
maximum: 999
readOnly: true
last_failed_payment:
description: The details for the last failed payment of the subscription.
readOnly: true
"$ref": "#/components/schemas/failed_payment_details"
required:
- outstanding_balance
- failed_payments_count
subscription:
title: Subscription
description: The subscription details.
type: object
allOf:
- "$ref": "#/components/schemas/subscription_status"
- properties:
id:
type: string
description: The PayPal-generated ID for the subscription.
minLength: 3
maxLength: 50
readOnly: true
plan_id:
type: string
description: The ID of the plan.
minLength: 3
maxLength: 50
start_time:
"$ref": "#/components/schemas/date_time"
quantity:
type: string
description: The quantity of the product in the subscription.
pattern: "^([0-9]+|([0-9]+)?[.][0-9]+)$"
minLength: 1
maxLength: 32
shipping_amount:
"$ref": "#/components/schemas/money"
subscriber:
"$ref": "#/components/schemas/subscriber"
billing_info:
readOnly: true
"$ref": "#/components/schemas/subscription_billing_info"
create_time:
readOnly: true
"$ref": "#/components/schemas/date_time"
update_time:
readOnly: true
"$ref": "#/components/schemas/date_time"
custom_id:
type: string
description: The custom id for the subscription. Can be invoice id.
minLength: 1
maxLength: 127
pattern: "^[\\x20-\\x7E]+"
plan_overridden:
type: boolean
description: Indicates whether the subscription has overridden any plan attributes.
readOnly: true
plan:
description: Inline plan details.
"$ref": "#/components/schemas/plan"
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
readOnly: true
"$ref": "#/components/schemas/link_description"
subscriptions.create-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- The value of a field does not conform to the expected format.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- title: INVALID_INTEGER_MIN_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MIN_VALUE
description:
type: string
enum:
- The integer value of a field is too small.
- title: INVALID_INTEGER_MAX_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MAX_VALUE
description:
type: string
enum:
- The integer value of a field is too large.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- Start time must be a valid future date and time.
- title: MISSING_REQUEST_BODY
properties:
issue:
type: string
enum:
- MISSING_REQUEST_BODY
description:
type: string
enum:
- Request body is missing.
- title: MISSING_REQUIRED_PARAMETER
properties:
issue:
type: string
enum:
- MISSING_REQUIRED_PARAMETER
description:
type: string
enum:
- A required field is missing.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
subscriptions.create-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 subscription creation; plan status should be active.
- title: SUBSCRIPTION_CANNOT_HAVE_QUANTITY
properties:
issue:
type: string
enum:
- SUBSCRIPTION_CANNOT_HAVE_QUANTITY
description:
type: string
enum:
- Subscription can't have quantity as the plan does not support quantity.
- title: CARD_SUBSCRIPTIONS_NOT_ENABLED
properties:
issue:
type: string
enum:
- CARD_SUBSCRIPTIONS_NOT_ENABLED
description:
type: string
enum:
- The account is not setup to be able to process subscriptions funded by card payments. Please contact PayPal customer support.
- title: 3DS_CARDS_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- 3DS_CARDS_NOT_SUPPORTED
description:
type: string
enum:
- Cards that require 3DS authentication not supported.
- title: INVALID_BILLING_CYCLE_SEQUENCE
properties:
issue:
type: string
enum:
- INVALID_BILLING_CYCLE_SEQUENCE
description:
type: string
enum:
- The provided billing cycle sequence is not available.
- title: INVALID_PRICING_SCHEME
properties:
issue:
type: string
enum:
- INVALID_PRICING_SCHEME
description:
type: string
enum:
- The override plan pricing scheme should be of the same type as that of the original plan.
- title: INVALID_PRICING_TIER_AMOUNT
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_AMOUNT
description:
type: string
enum:
- Free tiers are not supported.
- title: MISSING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- MISSING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- Tier(s) are missing for some quantities.
- title: OVERLAPPING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- OVERLAPPING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- The specified quantity overlaps with multiple pricing tiers.
- title: INVALID_PRICING_MODEL
properties:
issue:
type: string
enum:
- INVALID_PRICING_MODEL
description:
type: string
enum:
- The specified pricing model is not supported for trial billing cycle.
- title: FIXED_PRICE_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- FIXED_PRICE_NOT_SUPPORTED
description:
type: string
enum:
- Fixed price is not supported for tiered pricing schemes.
- title: INVALID_PRICING_TIER_QUANTITY
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_QUANTITY
description:
type: string
enum:
- Tier starting quantity must be less than ending quantity.
- title: CURRENCY_MISMATCH
properties:
issue:
type: string
enum:
- CURRENCY_MISMATCH
description:
type: string
enum:
- The currency code is different from the plan's currency code.
subscriptions.patch-400:
properties:
details:
type: array
items:
anyOf:
- title: UNSUPPORTED_PATCH_OPERATION
properties:
issue:
type: string
enum:
- UNSUPPORTED_PATCH_OPERATION
description:
type: string
enum:
- The specified patch operation not supported for this field.
- title: INVALID_PATCH_PATH
properties:
issue:
type: string
enum:
- INVALID_PATCH_PATH
description:
type: string
enum:
- The specified field cannot be patched.
- title: INVALID_PATCH_PATH
properties:
issue:
type: string
enum:
- INVALID_PATCH_PATH
description:
type: string
enum:
- Multiple operations on the same field are not allowed.
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- The value of a field does not conform to the expected format.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
- title: INVALID_STRING_MIN_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MIN_LENGTH
description:
type: string
enum:
- The value of a field is too short.
- title: INVALID_INTEGER_MIN_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MIN_VALUE
description:
type: string
enum:
- The integer value of a field is too small.
- title: INVALID_INTEGER_MAX_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MAX_VALUE
description:
type: string
enum:
- The integer value of a field is too large.
- title: MISSING_REQUEST_BODY
properties:
issue:
type: string
enum:
- MISSING_REQUEST_BODY
description:
type: string
enum:
- Request body is missing.
- title: MISSING_REQUIRED_PARAMETER
properties:
issue:
type: string
enum:
- MISSING_REQUIRED_PARAMETER
description:
type: string
enum:
- A required field is missing.
subscriptions.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: SUBSCRIPTION_STATUS_INVALID
properties:
issue:
type: string
enum:
- SUBSCRIPTION_STATUS_INVALID
description:
type: string
enum:
- Invalid subscription status for patch action; subscription status should be either active or suspended.
- title: CARD_SUBSCRIPTIONS_NOT_ENABLED
properties:
issue:
type: string
enum:
- CARD_SUBSCRIPTIONS_NOT_ENABLED
description:
type: string
enum:
- The account is not setup to be able to process subscriptions funded by card payments. Please contact PayPal customer support.
- title: 3DS_CARDS_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- 3DS_CARDS_NOT_SUPPORTED
description:
type: string
enum:
- Cards that require 3DS authentication not supported.
- title: BILLING_CYCLE_EXECUTION_COMPLETED
properties:
issue:
type: string
enum:
- BILLING_CYCLE_EXECUTION_COMPLETED
description:
type: string
enum:
- Update cannot be performed on a billing cycle that has completed execution.
- title: AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE
properties:
issue:
type: string
enum:
- AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE
description:
type: string
enum:
- The new outstanding balance cannot be greater than the current outstanding balance.
- title: INVALID_BILLING_TOTAL_CYCLES
properties:
issue:
type: string
enum:
- INVALID_BILLING_TOTAL_CYCLES
description:
type: string
enum:
- The total cycles cannot be less than the number of billing cycles completed.
- title: INVALID_PRICING_TIER_AMOUNT
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_AMOUNT
description:
type: string
enum:
- Free tiers are not supported.
- title: MISSING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- MISSING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- Tier(s) are missing for some quantities.
- title: OVERLAPPING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- OVERLAPPING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- The specified quantity overlaps with multiple pricing tiers.
- title: INVALID_PRICING_MODEL
properties:
issue:
type: string
enum:
- INVALID_PRICING_MODEL
description:
type: string
enum:
- The specified pricing model is not supported for trial billing cycle.
- title: FIXED_PRICE_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- FIXED_PRICE_NOT_SUPPORTED
description:
type: string
enum:
- Fixed price is not supported for tiered pricing schemes.
- title: INVALID_PRICING_TIER_QUANTITY
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_QUANTITY
description:
type: string
enum:
- Tier starting quantity must be less than ending quantity.
- title: INVALID_START_TIME
properties:
issue:
type: string
enum:
- INVALID_START_TIME
description:
type: string
enum:
- The start time cannot be updated for a subscription that has been activated.
- title: CURRENCY_MISMATCH
properties:
issue:
type: string
enum:
- CURRENCY_MISMATCH
description:
type: string
enum:
- The currency code is different from the subscription's currency code.
subscription_revise_request:
title: Subscription Modify Plan Request
description: The request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the `shipping_amount` and `shipping_address` values for the subscription. This type of update requires the buyer's consent.
type: object
properties:
plan_id:
type: string
description: The unique PayPal-generated ID for the plan.
minLength: 3
maxLength: 50
quantity:
type: string
description: The quantity of the product or service in the subscription.
pattern: "^([0-9]+|([0-9]+)?[.][0-9]+)$"
minLength: 1
maxLength: 32
shipping_amount:
description: The shipping charges.
"$ref": "#/components/schemas/money"
shipping_address:
description: The shipping address of the subscriber.
"$ref": "#/components/schemas/shipping_detail"
application_context:
"$ref": "#/components/schemas/application_context"
plan:
description: An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object. Any existing overrides will not be carried forward during subscription revise.
"$ref": "#/components/schemas/plan_override"
subscription_revise_response:
title: Update Product Quantity in Subscription Response
description: The response to a request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the `shipping_amount` and `shipping_address` values for the subscription. This type of update requires the buyer's consent.
type: object
allOf:
- "$ref": "#/components/schemas/subscription_revise_request"
- properties:
plan_overridden:
type: boolean
description: Indicates whether the subscription has overridden any plan attributes.
readOnly: true
links:
type: array
description: An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).
readOnly: true
items:
readOnly: true
"$ref": "#/components/schemas/link_description"
subscriptions.revise-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_PARAMETER_SYNTAX
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_SYNTAX
description:
type: string
enum:
- The value of a field does not conform to the expected format.
- title: INVALID_PARAMETER_VALUE
properties:
issue:
type: string
enum:
- INVALID_PARAMETER_VALUE
description:
type: string
enum:
- The value of a field is invalid.
- title: INVALID_INTEGER_MIN_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MIN_VALUE
description:
type: string
enum:
- The integer value of a field is too small.
- title: INVALID_INTEGER_MAX_VALUE
properties:
issue:
type: string
enum:
- INVALID_INTEGER_MAX_VALUE
description:
type: string
enum:
- The integer value of a field is too large.
- title: MISSING_REQUEST_BODY
properties:
issue:
type: string
enum:
- MISSING_REQUEST_BODY
description:
type: string
enum:
- Request body is missing.
- title: MISSING_REQUIRED_PARAMETER
properties:
issue:
type: string
enum:
- MISSING_REQUIRED_PARAMETER
description:
type: string
enum:
- A required field is missing.
subscriptions.revise-404:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_RESOURCE_ID
properties:
issue:
type: string
enum:
- INVALID_RESOURCE_ID
description:
type: string
enum:
- Requested resource ID was not found.
subscriptions.revise-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_PRODUCT_NOT_COMPATIBLE
properties:
issue:
type: string
enum:
- PLAN_PRODUCT_NOT_COMPATIBLE
description:
type: string
enum:
- The old and the new plans should be for the same product.
- title: INVALID_BILLING_CYCLE_SEQUENCE
properties:
issue:
type: string
enum:
- INVALID_BILLING_CYCLE_SEQUENCE
description:
type: string
enum:
- The provided billing cycle sequence is not available.
- title: INVALID_PRICING_SCHEME
properties:
issue:
type: string
enum:
- INVALID_PRICING_SCHEME
description:
type: string
enum:
- The override plan pricing scheme should be of the same type as that of the original plan.
- title: INVALID_PRICING_TIER_AMOUNT
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_AMOUNT
description:
type: string
enum:
- Free tiers are not supported.
- title: MISSING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- MISSING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- Tier(s) are missing for some quantities.
- title: OVERLAPPING_PRICING_SCHEME_TIERS
properties:
issue:
type: string
enum:
- OVERLAPPING_PRICING_SCHEME_TIERS
description:
type: string
enum:
- The specified quantity overlaps with multiple pricing tiers.
- title: INVALID_PRICING_MODEL
properties:
issue:
type: string
enum:
- INVALID_PRICING_MODEL
description:
type: string
enum:
- The specified pricing model is not supported for trial billing cycle.
- title: FIXED_PRICE_NOT_SUPPORTED
properties:
issue:
type: string
enum:
- FIXED_PRICE_NOT_SUPPORTED
description:
type: string
enum:
- Fixed price is not supported for tiered pricing schemes.
- title: INVALID_PRICING_TIER_QUANTITY
properties:
issue:
type: string
enum:
- INVALID_PRICING_TIER_QUANTITY
description:
type: string
enum:
- Tier starting quantity must be less than ending quantity.
- title: CURRENCY_MISMATCH
properties:
issue:
type: string
enum:
- CURRENCY_MISMATCH
description:
type: string
enum:
- The currency code is different from the plan's currency code.
subscription_suspend_request:
title: Suspend Subscription
description: The suspend subscription request details.
type: object
properties:
reason:
type: string
description: The reason for suspenson of the subscription.
minLength: 1
maxLength: 128
required:
- reason
subscriptions.suspend-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
subscriptions.suspend-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: SUBSCRIPTION_STATUS_INVALID
properties:
issue:
type: string
enum:
- SUBSCRIPTION_STATUS_INVALID
description:
type: string
enum:
- Invalid subscription status for suspend action; subscription status should be active.
subscription_cancel_request:
title: Cancel Subscription Request
description: The cancel subscription request details.
type: object
properties:
reason:
type: string
description: The reason for the cancellation of a subscription.
minLength: 1
maxLength: 128
required:
- reason
subscriptions.cancel-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
subscriptions.cancel-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: SUBSCRIPTION_STATUS_INVALID
properties:
issue:
type: string
enum:
- SUBSCRIPTION_STATUS_INVALID
description:
type: string
enum:
- Invalid subscription status for cancel action; subscription status should be active or suspended.
subscription_activate_request:
title: Activate Subscription Request
description: The activate subscription request details.
type: object
properties:
reason:
type: string
description: The reason for activation of a subscription. Required to reactivate the subscription.
minLength: 1
maxLength: 128
subscriptions.activate-400:
properties:
details:
type: array
items:
anyOf:
- title: INVALID_STRING_MAX_LENGTH
properties:
issue:
type: string
enum:
- INVALID_STRING_MAX_LENGTH
description:
type: string
enum:
- The value of a field is too long.
subscriptions.activate-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: SUBSCRIPTION_STATUS_INVALID
properties:
issue:
type: string
enum:
- SUBSCRIPTION_STATUS_INVALID
description:
type: string
enum:
- Invalid subscription status for activate action; subscription status should be suspended.
- title: SUBSCRIPTION_CANNOT_BE_ACTIVATED
properties:
issue:
type: string
enum:
- SUBSCRIPTION_CANNOT_BE_ACTIVATED
description:
type: string
enum:
- Subscription cannot be activated after payment failure threshold has reached.
- title: SUBSCRIPTION_CANNOT_BE_ACTIVATED
properties:
issue:
type: string
enum:
- SUBSCRIPTION_CANNOT_BE_ACTIVATED
description:
type: string
enum:
- This subscription should be activated by the system.
- title: SUBSCRIPTION_CANNOT_BE_ACTIVATED
properties:
issue:
type: string
enum:
- SUBSCRIPTION_CANNOT_BE_ACTIVATED
description:
type: string
enum:
- This subscription should be activated by the merchant.
subscription_capture_request:
title: Charge Amount from Subscriber
description: The charge amount from the subscriber.
type: object
properties:
note:
type: string
description: The reason or note for the subscription charge.
minLength: 1
maxLength: 128
capture_type:
type: string
description: The type of capture.
minLength: 1
maxLength: 24
pattern: "^[A-Z_]+$"
enum:
- OUTSTANDING_BALANCE
amount:
"$ref": "#/components/schemas/money"
description: The amount of the outstanding balance. This value cannot be greater than the current outstanding balance amount.
required:
- note
- capture_type
- amount
capture_status_details:
title: Capture Status Details
description: The details of the captured payment status.
type: object
properties:
reason:
description: The reason why the captured payment status is `PENDING` or `DENIED`.
type: string
enum:
- BUYER_COMPLAINT
- CHARGEBACK
- ECHECK
- INTERNATIONAL_WITHDRAWAL
- OTHER
- PENDING_REVIEW
- RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
- REFUNDED
- TRANSACTION_APPROVED_AWAITING_FUNDING
- UNILATERAL
- VERIFICATION_REQUIRED
capture_status:
type: object
title: Capture Status
description: The status of a captured payment.
properties:
status:
description: The status of the captured payment.
type: string
readOnly: true
enum:
- COMPLETED
- DECLINED
- PARTIALLY_REFUNDED
- PENDING
- REFUNDED
status_details:
description: The details of the captured payment status.
readOnly: true
"$ref": "#/components/schemas/capture_status_details"
amount_with_breakdown:
type: object
title: Amount with Breakdown
description: The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.
properties:
gross_amount:
description: The amount for this transaction.
readOnly: true
"$ref": "#/components/schemas/money"
total_item_amount:
description: The item total for the transaction.
readOnly: true
"$ref": "#/components/schemas/money"
fee_amount:
description: The fee details for the transaction.
readOnly: true
"$ref": "#/components/schemas/money"
shipping_amount:
description: The shipping amount for the transaction.
readOnly: true
"$ref": "#/components/schemas/money"
tax_amount:
description: The tax amount for the transaction.
readOnly: true
"$ref": "#/components/schemas/money"
net_amount:
description: The net amount that the payee receives for this transaction in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee.
readOnly: true
"$ref": "#/components/schemas/money"
required:
- gross_amount
email_address:
type: string
description: The internationalized email address.Note: Up to 64 characters are allowed before and 255 characters are allowed after theformat: ppaas_common_email_address_v2 minLength: 3 maxLength: 254 pattern: ^.+@[^"\-].+$ transaction: title: Transaction Details description: The transaction details. type: object allOf: - "$ref": "#/components/schemas/capture_status" - properties: id: type: string description: The PayPal-generated transaction ID. minLength: 3 maxLength: 50 readOnly: true amount_with_breakdown: "$ref": "#/components/schemas/amount_with_breakdown" payer_name: description: The name of the customer. readOnly: true "$ref": "#/components/schemas/name" payer_email: description: The email ID of the customer. readOnly: true "$ref": "#/components/schemas/email_address" time: description: The date and time when the transaction was processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). readOnly: true "$ref": "#/components/schemas/date_time" required: - id - amount_with_breakdown - time subscriptions.capture-400: properties: details: type: array items: anyOf: - title: MISSING_REQUEST_BODY properties: issue: type: string enum: - MISSING_REQUEST_BODY description: type: string enum: - Request body is missing. - title: INVALID_PARAMETER_VALUE properties: issue: type: string enum: - INVALID_PARAMETER_VALUE description: type: string enum: - The value of a field is invalid. - title: INVALID_STRING_MAX_LENGTH properties: issue: type: string enum: - INVALID_STRING_MAX_LENGTH description: type: string enum: - The value of a field is too long. - title: MISSING_REQUIRED_PARAMETER properties: issue: type: string enum: - MISSING_REQUIRED_PARAMETER description: type: string enum: - A required field is missing. subscriptions.capture-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: SUBSCRIBER_ACCOUNT_LOCKED properties: issue: type: string enum: - SUBSCRIBER_ACCOUNT_LOCKED description: type: string enum: - Subscriber Account Locked. - title: SUBSCRIBER_ACCOUNT_CLOSED properties: issue: type: string enum: - SUBSCRIBER_ACCOUNT_CLOSED description: type: string enum: - Subscriber Account Closed. - title: SUBSCRIBER_ACCOUNT_RESTRICTED properties: issue: type: string enum: - SUBSCRIBER_ACCOUNT_RESTRICTED description: type: string enum: - Subscriber Account Restricted. - title: SUBSCRIPTION_STATUS_INVALID properties: issue: type: string enum: - SUBSCRIPTION_STATUS_INVALID description: type: string enum: - Invalid subscription status for capture action; subscription status should be active or suspended or expired. - title: ZERO_OUTSTANDING_BALANCE properties: issue: type: string enum: - ZERO_OUTSTANDING_BALANCE description: type: string enum: - Current outstanding balance should be greater than zero. - title: CURRENCY_MISMATCH properties: issue: type: string enum: - CURRENCY_MISMATCH description: type: string enum: - The currency code is different from the subscription's currency code. - title: AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE properties: issue: type: string enum: - AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE description: type: string enum: - The capture amount can not be greater than the current outstanding balance. transactions_list: title: List Transactions description: The list transactions for a subscription request details. type: object properties: transactions: type: array description: An array of transactions. minItems: 0 maxItems: 32767 items: "$ref": "#/components/schemas/transaction" 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" subscriptions.transactions-400: properties: details: type: array items: anyOf: - title: INVALID_PARAMETER_SYNTAX properties: issue: type: string enum: - INVALID_PARAMETER_SYNTAX description: type: string enum: - The value of a field does not conform to the expected format. - 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. parameters: prefer: name: Prefer in: header description: The preferred server response upon successful completion of the request. Value is:@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
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.