| 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 |
gross_amount minus the paypal_fee.
readOnly: true
$ref: "#/components/schemas/money"
required:
- gross_amount
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
pattern: ^.*$
deprecated: true
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"
deprecated: true
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
deprecated: true
enum:
- GET_FROM_FILE
- NO_SHIPPING
- SET_PROVIDED_ADDRESS
oneOf:
- type: string
enum:
- GET_FROM_FILE
description: Get the customer-provided shipping address on the PayPal site.
- type: string
enum:
- NO_SHIPPING
description: Redacts the shipping address from the PayPal site. Recommended for
digital goods.
- type: string
enum:
- SET_PROVIDED_ADDRESS
description: Get the merchant-provided address. The customer cannot change this
address on the PayPal site. If merchant does not pass an
address, customer can choose the address on PayPal pages.
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
deprecated: true
enum:
- CONTINUE
- SUBSCRIBE_NOW
oneOf:
- type: string
enum:
- CONTINUE
description: After you redirect the customer to the PayPal subscription consent
page, a Continue button appears. Use this
option when you want to control the activation of the
subscription and do not want PayPal to activate the
subscription.
- type: string
enum:
- SUBSCRIBE_NOW
description: After you redirect the customer to the PayPal subscription consent
page, a Subscribe Now button appears. Use this
option when you want PayPal to activate the subscription.
payment_method:
description: The customer and merchant payment preferences.
deprecated: true
type: object
title: Payment Method
properties:
payee_preferred:
$ref: "#/components/schemas/payee_payment_method_preference"
return_url:
type: string
format: uri
description: The URL where the customer is redirected after the customer
approves the payment.
minLength: 10
maxLength: 4000
deprecated: true
cancel_url:
type: string
format: uri
description: The URL where the customer is redirected after the customer cancels
the payment.
minLength: 10
maxLength: 4000
deprecated: true
required:
- return_url
- cancel_url
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"
billing_cycle:
title: Billing Cycle
description: The billing cycle details.
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"
frequency:
description: The frequency details for this billing cycle.
$ref: "#/components/schemas/frequency"
tenure_type:
type: string
description: The tenure type of the billing cycle. In case of a plan having
trial cycle, only 2 trial cycles are allowed per plan.
minLength: 1
maxLength: 24
pattern: ^[A-Z_]+$
enum:
- REGULAR
- TRIAL
oneOf:
- type: string
enum:
- REGULAR
description: A regular billing cycle.
- type: string
enum:
- TRIAL
description: A trial billing cycle.
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
default: 1
required:
- frequency
- tenure_type
- sequence
billing_cycle_list:
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"
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
billing_cycle_override_list:
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"
bin_details:
type: object
title: Bin Details
description: Bank Identification Number (BIN) details used to fund a payment.
properties:
bin:
type: string
description: The Bank Identification Number (BIN) signifies the number that is
being used to identify the granular level details (except the PII
information) of the card.
pattern: ^[0-9]+$
maxLength: 25
minLength: 1
issuing_bank:
type: string
description: The issuer of the card instrument.
minLength: 1
maxLength: 64
bin_country_code:
description: The [two-character ISO-3166-1 country
code](/docs/integration/direct/rest/country-codes/) of the bank.
$ref: "#/components/schemas/country_code-2"
products:
$ref: "#/components/schemas/products_list"
card_attributes:
type: object
title: Card Attributes
description: Additional attributes associated with the use of this card.
properties:
customer:
$ref: "#/components/schemas/card_customer"
vault:
description: Instruction to vault the card based on the specified strategy.
$ref: "#/components/schemas/vault_instruction_base"
verification:
description: Instruction to optionally verify the card based on the specified
strategy.
$ref: "#/components/schemas/card_verification"
card_attributes_response:
type: object
title: Card Attributes Response
description: Additional attributes associated with the use of this card.
properties:
vault:
$ref: "#/components/schemas/card_vault_response"
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
- DINERS
- ELO
- HIPER
- HIPERCARD
- RUPAY
- GE
- SYNCHRONY
- EFTPOS
- UNKNOWN
oneOf:
- type: string
enum:
- VISA
description: Visa card.
- type: string
enum:
- MASTERCARD
description: Mastercard card.
- type: string
enum:
- DISCOVER
description: Discover card.
- type: string
enum:
- AMEX
description: American Express card.
- type: string
enum:
- SOLO
description: Solo debit card.
- type: string
enum:
- JCB
description: Japan Credit Bureau card.
- type: string
enum:
- STAR
description: Military Star card.
- type: string
enum:
- DELTA
description: Delta Airlines card.
- type: string
enum:
- SWITCH
description: Switch credit card.
- type: string
enum:
- MAESTRO
description: Maestro credit card.
- type: string
enum:
- CB_NATIONALE
description: Carte Bancaire (CB) credit card.
- type: string
enum:
- CONFIGOGA
description: Configoga credit card.
- type: string
enum:
- CONFIDIS
description: Confidis credit card.
- type: string
enum:
- ELECTRON
description: Visa Electron credit card.
- type: string
enum:
- CETELEM
description: Cetelem credit card.
- type: string
enum:
- CHINA_UNION_PAY
description: China union pay credit card.
- type: string
enum:
- DINERS
description: The Diners Club International banking and payment services
capability network owned by Discover Financial Services (DFS), one
of the most recognized brands in US financial services.
- type: string
enum:
- ELO
description: The Brazilian Elo card payment network.
- type: string
enum:
- HIPER
description: The Hiper - Ingenico ePayment network.
- type: string
enum:
- HIPERCARD
description: The Brazilian Hipercard payment network that's widely accepted in
the retail market.
- type: string
enum:
- RUPAY
description: The RuPay payment network.
- type: string
enum:
- GE
description: The GE Credit Union 3Point card payment network.
- type: string
enum:
- SYNCHRONY
description: The Synchrony Financial (SYF) payment network.
- type: string
enum:
- EFTPOS
description: The Electronic Fund Transfer At Point of Sale(EFTPOS) Debit card
payment network.
- type: string
enum:
- UNKNOWN
description: UNKNOWN payment network.
card_brand_list:
type: array
description: Array of brands or networks associated with the card.
readOnly: true
minItems: 1
maxItems: 256
items:
$ref: "#/components/schemas/card_brand"
card_customer:
type: object
title: Card Customer Information
description: The details about a customer in PayPal's system of record.
allOf:
- $ref: "#/components/schemas/customer"
- properties:
merchant_customer_id:
description: Merchants and partners may already have a data-store where their
customer information is persisted. Use merchant_customer_id to
associate the PayPal-generated customer.id to your
representation of a customer.
type: string
minLength: 1
maxLength: 64
pattern: ^[0-9a-zA-Z-_.^*$@#]+$
card_from_request:
type: object
title: Card from Request
description: Representation of card details as received in the request.
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"
last_digits:
type: string
description: The last digits of the payment card.
pattern: "[0-9]{2,}"
minLength: 2
maxLength: 4
readOnly: true
card_request:
type: object
title: Card
description: The payment card to use to fund a payment. Can be a credit or debit card.
properties:
name:
type: string
description: The card holder's name as it appears on the card.
maxLength: 300
minLength: 1
pattern: ^.{1,300}$
number:
type: string
description: The primary account number (PAN) for the payment card.
pattern: ^[0-9]{13,19}$
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) For
example: 2028-04"
$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}$
minLength: 3
maxLength: 4
type:
description: The payment card type.
$ref: "#/components/schemas/card_type"
brand:
description: The card brand or network. Typically used in the response.
$ref: "#/components/schemas/card_brand"
billing_address:
description: "The portable international postal address. Maps to
[AddressValidationMetadata](https://github.com/googlei18n/libaddres\
sinput/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)."
type: object
title: Portable Postal Address (Medium-Grained)
properties:
address_line_1:
type: string
description: The first line of the address, such as number and street, for
example, `173 Drury Lane`. Needed for data entry, and Compliance
and Risk checks. This field needs to pass the full address.
maxLength: 300
address_line_2:
type: string
description: The second line of the address, for example, a suite or apartment
number.
maxLength: 300
admin_area_2:
type: string
description: A city, town, or village. Smaller than `admin_area_level_1`.
maxLength: 120
admin_area_1:
type: string
description: The highest-level sub-division in a country, which is usually a
province, state, or ISO-3166-2 subdivision. This data is
formatted for postal delivery, for example, `CA` and not
`California`. Value, by country, is:Note: The country code for Great Britain isformat: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ country_code-2: type: string description: The [two-character ISO 3166-1 code](/api/rest/reference/country-codes/) that identifies the country or region.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.
Note: The country code for Great Britain isformat: ppaas_common_country_code_v2 maxLength: 2 minLength: 2 pattern: ^([A-Z]{2}|C2)$ currency_code: description: The [three-character ISO-4217 currency code](/api/rest/reference/currency-codes/) that identifies the currency. type: string minLength: 3 maxLength: 3 x-security-classification: data_class: class4 data_category: INTRINSIC customer: type: object title: Customer Information description: The details about a customer in PayPal's system of record. properties: id: $ref: "#/components/schemas/merchant_partner_customer_id" email_address: description: Email address of the buyer as provided to the merchant or on file with the merchant. Email Address is required if you are processing the transaction using PayPal Guest Processing which is offered to select partners and merchants. For all other use cases we do not expect partners/merchant to send email_address of their customer. $ref: "#/components/schemas/email" phone: description: The phone number of the buyer as provided to the merchant or on file with the merchant. The `phone.phone_number` supports only `national_number`. $ref: "#/components/schemas/phone_with_type" 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 oneOf: - type: string enum: - REGULAR description: A regular billing cycle. - type: string enum: - TRIAL description: A trial billing cycle. 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 betweenGBand 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.
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
cycle_execution_list:
type: array
description: The trial and regular billing executions.
minItems: 0
maxItems: 3
items:
$ref: "#/components/schemas/cycle_execution"
readOnly: true
date_time:
type: string
description: The date and time, in [Internet date and time
format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are
required while fractional seconds are
optional.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})$ 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])$ definitions-link_description_list: type: array description: An array of request-related HATEOAS links. readOnly: true minItems: 1 maxItems: 10 items: $ref: "#/components/schemas/link_description" 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 minLength: 3 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])+)\]) email_address: type: string description: The internationalized email address.@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
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: ^(?:[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])?|\[(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-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])+)\])$ enrolled: type: string minLength: 1 maxLength: 255 pattern: ^[0-9A-Z_]+$ description: Status of Authentication eligibility. enum: - Y - N - U - B oneOf: - type: string enum: - Y description: Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl. - type: string enum: - N description: No. The bank is not participating in 3-D Secure protocol. - type: string enum: - U description: Unavailable. The DS or ACS is not available for authentication at the time of the request. - type: string enum: - B description: Bypass. The merchant authentication rule is triggered to bypass authentication. error_400: type: object title: Bad Request Error description: Request is not well-formed, syntactically incorrect, or violates schema. properties: name: type: string enum: - INVALID_REQUEST message: type: string enum: - Request is not well-formed, syntactically incorrect, or violates schema. 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_401: type: object title: Unauthorized Error description: Authentication failed due to missing Authorization header, or invalid authentication credentials. properties: name: type: string enum: - AUTHENTICATION_FAILURE message: type: string enum: - Authentication failed due to missing authorization header, or invalid authentication credentials. 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_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_404: type: object title: Not found Error description: The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available. properties: name: type: string enum: - RESOURCE_NOT_FOUND message: type: string enum: - The specified resource does not exist. 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_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" error_415: type: object title: Unsupported Media Type Error description: The server does not support the request payload's media type. properties: name: type: string enum: - UNSUPPORTED_MEDIA_TYPE message: type: string enum: - The server does not support the request payload's media type. 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" error_500: type: object title: Internal Server Error description: This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server. properties: name: type: string enum: - INTERNAL_SERVER_ERROR message: type: string enum: - An internal server error occurred. 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" examples: - name: INTERNAL_SERVER_ERROR message: An internal server error occurred. debug_id: 90957fca61718 links: - href: https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR rel: information_link error_503: type: object title: Service Unavailable Error description: The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime. properties: name: type: string enum: - SERVICE_UNAVAILABLE message: type: string enum: - Service Unavailable. 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" examples: - name: SERVICE_UNAVAILABLE message: Service Unavailable. debug_id: 90957fca61718 information_link: https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE 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" 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 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 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 oneOf: - type: string enum: - PAYMENT_DENIED description: PayPal declined the payment due to one or more customer issues. - type: string enum: - INTERNAL_SERVER_ERROR description: An internal server error has occurred. - type: string enum: - PAYEE_ACCOUNT_RESTRICTED description: The payee account is not in good standing and cannot receive payments. - type: string enum: - PAYER_ACCOUNT_RESTRICTED description: The payer account is not in good standing and cannot make payments. - type: string enum: - PAYER_CANNOT_PAY description: Payer cannot pay for this transaction. - type: string enum: - SENDING_LIMIT_EXCEEDED description: The transaction exceeds the payer's sending limit. - type: string enum: - TRANSACTION_RECEIVING_LIMIT_EXCEEDED description: The transaction exceeds the receiver's receiving limit. - type: string enum: - CURRENCY_MISMATCH description: The transaction is declined due to a 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 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 oneOf: - type: string enum: - DAY description: A daily billing cycle. - type: string enum: - WEEK description: A weekly billing cycle. - type: string enum: - MONTH description: A monthly billing cycle. - type: string enum: - YEAR description: A yearly billing cycle. 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`:@sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted@sign exists.
Interval
unit | Maximum interval count |
|---|---|
DAY | 365 |
WEEK | 52 |
MONTH | 12 |
YEAR | 1 |
value parameter
defines the value to add. For more information, see 4.1.
add.
- type: string
enum:
- 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.
- type: string
enum:
- 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.
- type: string
enum:
- 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.
- type: string
enum:
- 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.
- type: string
enum:
- 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, copy, and
move operations do not require a value. Since JSON Patch allows
any type for value, the type property is
not specified.
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"
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
oneOf:
- type: string
enum:
- UNRESTRICTED
description: Accepts any type of payment from the customer.
- type: string
enum:
- IMMEDIATE_PAYMENT_REQUIRED
description: Accepts only immediate payment from the customer. For example,
credit card, PayPal balance, or instant ACH. Ensures that at the
time of capture, the payment does not have the `pending` status.
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"
payer_holding_preference: {}
payment_initiator:
type: string
minLength: 1
maxLength: 255
pattern: ^[0-9A-Z_]+$
description: The person or party who initiated or triggered the payment.
enum:
- CUSTOMER
- MERCHANT
oneOf:
- type: string
enum:
- CUSTOMER
description: Payment is initiated with the active engagement of the customer.
e.g. a customer checking out on a merchant website.
- type: string
enum:
- MERCHANT
description: Payment is initiated by merchant on behalf of the customer without
the active engagement of customer. e.g. a merchant charging the
monthly payment of a subscription to the customer.
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
oneOf:
- type: string
enum:
- CONTINUE
description: Continues the subscription if the initial payment for the setup
fails.
- type: string
enum:
- CANCEL
description: Cancels the subscription if the initial payment for the setup
fails.
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
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
oneOf:
- type: string
enum:
- CONTINUE
description: Continues the subscription if the initial payment for the setup
fails.
- type: string
enum:
- CANCEL
description: Cancels the subscription if the initial payment for the setup
fails.
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
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_request"
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"
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]+))$
phone_type:
type: string
title: Phone Type
description: The phone type.
enum:
- FAX
- HOME
- MOBILE
- OTHER
- PAGER
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).
type: object
title: Phone
properties:
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}?$
required:
- national_number
required:
- phone_number
plan:
title: Plan
description: The plan details.
type: object
properties:
id:
type: string
description: The unique PayPal-generated ID for the plan.
minLength: 26
maxLength: 26
pattern: ^P-[A-Z0-9]*$
readOnly: true
product_id:
type: string
description: The ID for the product.
minLength: 22
maxLength: 22
pattern: ^PROD-[A-Z0-9]*$
name:
type: string
description: The plan name.
minLength: 1
maxLength: 127
pattern: ^.*$
status:
type: string
description: The plan status.
minLength: 1
maxLength: 24
pattern: ^[A-Z_]+$
enum:
- CREATED
- INACTIVE
- ACTIVE
oneOf:
- type: string
enum:
- CREATED
description: The plan was created. You cannot create subscriptions for a plan in
this state.
- type: string
enum:
- INACTIVE
description: The plan is inactive.
- type: string
enum:
- ACTIVE
description: The plan is active. You can only create subscriptions for a plan in
this state.
description:
type: string
description: The detailed description of the plan.
minLength: 1
maxLength: 127
pattern: ^.*$
billing_cycles:
$ref: "#/components/schemas/billing_cycle_list"
payment_preferences:
$ref: "#/components/schemas/payment_preferences"
merchant_preferences:
$ref: "#/components/schemas/merchant_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:
$ref: "#/components/schemas/link_description_list"
plan_collection:
title: Plan Collection
description: The list of plans with details.
type: object
properties:
plans:
$ref: "#/components/schemas/plan_list"
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:
$ref: "#/components/schemas/link_description_list"
plan_list:
type: array
minItems: 0
maxItems: 32767
description: An array of plans.
items:
$ref: "#/components/schemas/plan"
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:
$ref: "#/components/schemas/billing_cycle_override_list"
payment_preferences:
$ref: "#/components/schemas/payment_preferences_override"
taxes:
$ref: "#/components/schemas/taxes_override"
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: 22
maxLength: 22
pattern: ^PROD-[A-Z0-9]*$
name:
type: string
description: The plan name.
minLength: 1
maxLength: 127
pattern: ^.*$
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
oneOf:
- type: string
enum:
- CREATED
description: The plan was created. You cannot create subscriptions for a plan in
this state.
- type: string
enum:
- INACTIVE
description: The plan is inactive.
- type: string
enum:
- ACTIVE
description: The plan is active. You can only create subscriptions for a plan in
this state.
description:
type: string
description: The detailed description of the plan.
minLength: 1
maxLength: 127
pattern: ^.*$
billing_cycles:
$ref: "#/components/schemas/billing_cycle_list"
payment_preferences:
$ref: "#/components/schemas/payment_preferences"
merchant_preferences:
$ref: "#/components/schemas/merchant_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.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.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.
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.
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.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.
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
oneOf:
- type: string
enum:
- VOLUME
description: A volume pricing model.
- type: string
enum:
- TIERED
description: A tiered pricing model.
tiers:
$ref: "#/components/schemas/pricing_tier_list"
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"
pricing_tier:
title: Pricing Tier
description: The pricing tier details.
type: object
properties:
starting_quantity:
type: string
description: The starting quantity for the tier.
pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$
minLength: 1
maxLength: 32
ending_quantity:
type: string
description: The ending quantity for the tier. Optional for the last tier.
pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$
minLength: 1
maxLength: 32
amount:
description: The pricing amount for the tier.
$ref: "#/components/schemas/money"
required:
- starting_quantity
- amount
pricing_tier_list:
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"
products:
type: string
description: This value provides the category of the BIN.
minLength: 1
maxLength: 255
products_list:
type: array
description: "The type of card product assigned to the BIN by the issuer. These
values are defined by the issuer and may change over time. Some examples
include: PREPAID_GIFT, CONSUMER, CORPORATE."
items:
$ref: "#/components/schemas/products"
minItems: 1
maxItems: 256
shipping_detail:
type: object
description: The shipping details.
title: Shipping Details
properties:
name:
description: The name of the party.
type: object
title: Name
properties:
full_name:
type: string
description: When the party is a person, the party's full name.
maxLength: 300
email_address:
description: The email address of the recipient of the shipped items, which may
belong to either the payer, or an alternate contact, for delivery.
$ref: "#/components/schemas/email_address"
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).
type: object
title: Phone
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}?$
required:
- country_code
- national_number
type:
title: Fulfillment Type
description: A classification for the method of purchase fulfillment (e.g
shipping, in-store pickup, etc). Either `type` or `options` may be
present, but not both.
type: string
minLength: 1
maxLength: 255
pattern: ^[0-9A-Z_]+$
enum:
- SHIPPING
- PICKUP_IN_PERSON
- PICKUP_IN_STORE
- PICKUP_FROM_PERSON
oneOf:
- type: string
enum:
- SHIPPING
description: The payer intends to receive the items at a specified address.
- type: string
enum:
- PICKUP_IN_PERSON
description: DEPRECATED. Please use "PICKUP_FROM_PERSON" instead.
- type: string
enum:
- PICKUP_IN_STORE
description: The payer intends to pick up the item(s) from the payee's physical
store. Also termed as BOPIS, "Buy Online, Pick-up in Store".
Seller protection is provided with this option.
- type: string
enum:
- PICKUP_FROM_PERSON
description: The payer intends to pick up the item(s) from the payee in person.
Also termed as BOPIP, "Buy Online, Pick-up in Person". Seller
protection is not available, since the payer is receiving the
item from the payee in person, and can validate the item prior
to payment.
options:
$ref: "#/components/schemas/shipping_option_list"
address:
description: "The portable international postal address. Maps to
[AddressValidationMetadata](https://github.com/googlei18n/libaddres\
sinput/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)."
type: object
title: Portable Postal Address (Medium-Grained)
properties:
address_line_1:
type: string
description: The first line of the address, such as number and street, for
example, `173 Drury Lane`. Needed for data entry, and Compliance
and Risk checks. This field needs to pass the full address.
maxLength: 300
address_line_2:
type: string
description: The second line of the address, for example, a suite or apartment
number.
maxLength: 300
admin_area_2:
type: string
description: A city, town, or village. Smaller than `admin_area_level_1`.
maxLength: 120
admin_area_1:
type: string
description: The highest-level sub-division in a country, which is usually a
province, state, or ISO-3166-2 subdivision. This data is
formatted for postal delivery, for example, `CA` and not
`California`. Value, by country, is:status.details.
- type: string
enum:
- REFUNDED
description: An amount greater than or equal to this captured payment's amount
was refunded to the payer.
- type: string
enum:
- FAILED
description: There was an error while capturing payment.
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
transaction_list:
type: array
description: An array of transactions.
minItems: 0
maxItems: 32767
items:
$ref: "#/components/schemas/transaction"
transactions_list:
title: List Transactions
description: The list transactions for a subscription request details.
type: object
properties:
transactions:
$ref: "#/components/schemas/transaction_list"
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:
$ref: "#/components/schemas/link_description_list"
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_scheme_request_list:
type: array
description: An array of pricing schemes.
minItems: 1
maxItems: 99
items:
$ref: "#/components/schemas/update_pricing_scheme_request"
update_pricing_schemes_list_request:
title: Update Pricing Scheme Request
description: The update pricing scheme request details.
type: object
properties:
pricing_schemes:
$ref: "#/components/schemas/update_pricing_scheme_request_list"
required:
- pricing_schemes
vault_instruction_base:
type: object
title: Vault Instruction Base
description: Basic vault instruction specification that can be extended by
specific payment sources that supports vaulting.
properties:
store_in_vault:
$ref: "#/components/schemas/store_in_vault_instruction"
responses:
default:
description: The default response.
content:
application/json:
schema:
$ref: "#/components/schemas/error_default"
parameters:
content_type:
name: Content-Type
in: header
description: The media type. Required for operations with a request body. The
value is `application/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.70 plan IDs. URLs should not exceed a length of
2000 characters.
required: false
schema:
type: string
minimum: 3
maximum: 1890
statuses:
name: statuses
in: query
description: Filters the response by list of subscription statuses.
schema:
type: string
minLength: 1
maxLength: 70
pattern: ^[A-Z_,]+$
enum:
- ACTIVE
- SUSPENDED
- CANCELLED
- EXPIRED
oneOf:
- enum:
- ACTIVE
description: Active state of the subscription.
- enum:
- SUSPENDED
description: Suspended state of the subscription.
- enum:
- CANCELLED
description: Cancelled state of the subscription.
- enum:
- EXPIRED
description: Expired state of the subscription.
created_after:
name: created_after
in: query
required: false
description: Filters the response by subscription creation start time for a
range of subscriptions.
schema:
type: string
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})$
created_before:
name: created_before
in: query
required: false
description: Filters the response by subscription creation end time for a range
of subscriptions.
schema:
type: string
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})$
status_updated_before:
name: status_updated_before
in: query
required: false
description: Filters the response by status update start time for a range of
subscriptions.
schema:
type: string
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})$
status_updated_after:
name: status_updated_after
in: query
required: false
description: Filters the response by status update end time for a range of
subscriptions.
schema:
type: string
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})$
filter:
name: filter
in: query
description: Filter the response using complex expressions that could use
comparison operators like ge, gt, le, lt and logical operators such as
'and' and 'or'.
required: false
schema:
type: string
minLength: 0
maxLength: 100
fields:
name: fields
in: query
description: List of fields that are to be returned in the response. Possible
value for fields are last_failed_payment and plan.
schema:
type: string
minLength: 1
maxLength: 100
start_time:
name: start_time
in: query
required: true
description: The start time of the range of transactions to list.
schema:
type: string
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})$
end_time:
name: end_time
in: query
required: true
description: The end time of the range of transactions to list.
schema:
type: string
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})$