subscription

Schema Information

Properties

status

Type: string

Enum: "APPROVAL_PENDING", "APPROVED", "ACTIVE", "SUSPENDED", "CANCELLED", "EXPIRED"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The status of the subscription.

status_change_note

Type: string

Pattern: ^.*$

Min length: 1

Max length: 128

The reason or notes for the status of the subscription.

status_update_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

id

Type: string

Min length: 3

Max length: 50

The PayPal-generated ID for the subscription.

plan_id

Type: string

Min length: 3

Max length: 50

The ID of the plan.

start_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

quantity

Type: string

Pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$

Min length: 1

Max length: 32

The quantity of the product in the subscription.

shipping_amount

Type: object

The currency and amount for a financial transaction, such as a balance or payment due.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

subscriber

Type: object

Format: payer_v1

The customer who approves and pays for the order. The customer is also known as the payer.

The subscriber response information.

email_address

Type: string

Format: merchant_common_email_address_v2

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])+)\])

Min length: 3

Max length: 254

The email address of the payer.

payer_id

Type: string

Format: ppaas_payer_id_v3

Pattern: ^[2-9A-HJ-NP-Z]{13}$

Min length: 13

Max length: 13

The PayPal-assigned ID for the payer.

name

Type: object

The name of the party.

given_name

Type: string

Max length: 140

When the party is a person, the party's given, or first, name.

surname

Type: string

Max length: 140

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.

shipping_address

Type: object

The shipping details.

name

Type: object

The name of the party.

full_name

Type: string

Max length: 300

When the party is a person, the party's full name.

email_address

Type: string

Format: ppaas_common_email_address_v2

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])+)\])$

Min length: 3

Max length: 254

The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery.

phone_number

Type: object

The phone number, in its canonical international E.164 numbering plan format.

country_coderequired

Type: string

Pattern: ^[0-9]{1,3}?$

Min length: 1

Max length: 3

The country calling code (CC), in its canonical international E.164 numbering plan format. 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).

national_numberrequired

Type: string

Pattern: ^[0-9]{1,14}?$

Min length: 1

Max length: 14

The national number, in its canonical international E.164 numbering plan format. 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).

type

Type: string

Enum: "SHIPPING", "PICKUP_IN_PERSON", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

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.

options

Type: array

An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.

Array Items

items

Type: object

The options that the payee or merchant offers to the payer to ship or pick up their items.

idrequired

Type: string

Max length: 127

A unique ID that identifies a payer-selected shipping option.

labelrequired

Type: string

Max length: 127

A description that the payer sees, which helps them choose an appropriate shipping option. For example, Free Shipping, USPS Priority Shipping, Expédition prioritaire USPS, or USPS yōuxiān fā huò. Localize this description to the payer's locale.

type

Type: string

Enum: "SHIPPING", "PICKUP", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"

A classification for the method of purchase fulfillment.

amount

Type: object

The shipping cost for the selected option.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

selectedrequired

Type: boolean

If the API request sets selected = true, it represents the shipping option that the payee or merchant expects to be pre-selected for the payer when they first view the shipping.options in the PayPal Checkout experience. As part of the response if a shipping.option contains selected=true, it represents the shipping option that the payer selected during the course of checkout with PayPal. Only one shipping.option can be set to selected=true.

address

Type: object

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1

Type: string

Max length: 300

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.

address_line_2

Type: string

Max length: 300

The second line of the address, for example, a suite or apartment number.

admin_area_2

Type: string

Max length: 120

A city, town, or village. Smaller than admin_area_level_1.

admin_area_1

Type: string

Max length: 300

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:

UK. A county.
US. A state.
Canada. A province.
Japan. A prefecture.
Switzerland. A kanton.

postal_code

Type: string

Max length: 60

The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

country_coderequired

Type: string

Format: ppaas_common_country_code_v2

Pattern: ^([A-Z]{2}|C2)$

Min length: 2

Max length: 2

The 2-character ISO 3166-1 code that identifies the country or region.

payment_source

Type: object

The payment source used to fund the payment.

card

Type: object

The payment card to use to fund a payment. Card can be a credit or debit card.

The payment card used to fund the payment. Card can be a credit or debit card.

name

Type: string

Min length: 2

Max length: 300

The card holder's name as it appears on the card.

last_digits

Type: string

Pattern: [0-9]{2,}

The last digits of the payment card.

brand

Type: string

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"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The card brand or network. Typically used in the response.

available_networks

Type: array

Array of brands or networks associated with the card.

Array Items

items

Type: string

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"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The card network or brand. Applies to credit, debit, gift, and payment cards.

type

Type: string

Enum: "CREDIT", "DEBIT", "PREPAID", "STORE", "UNKNOWN"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The payment card type.

authentication_result

Type: object

Results of Authentication such as 3D Secure.

liability_shift

Type: string

Enum: "NO", "POSSIBLE", "UNKNOWN"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Liability shift indicator. The outcome of the issuer's authentication.

three_d_secure

Type: object

Results of 3D Secure Authentication.

authentication_status

Type: string

Enum: "Y", "N", "U", "A", "C", "R", "D", "I"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

The outcome of the issuer's authentication.

enrollment_status

Type: string

Enum: "Y", "N", "U", "B"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Status of authentication eligibility.

attributes

Type: object

Additional attributes associated with the use of this card.

vault

Type: object

The details about a saved Card payment source.

id

Type: string

Min length: 1

Max length: 255

The PayPal-generated ID for the saved payment source.

status

Type: string

Enum: "VAULTED", "CREATED", "APPROVED"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

The vault status.

links

Type: array

An array of request-related HATEOAS links.

Array Items

items

Type: object

The request-related HATEOAS link information.

hrefrequired

Type: string

The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the $, (, and ) characters. The href is the key HATEOAS component that links a completed call with a subsequent call.

relrequired

Type: string

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

method

Type: string

Enum: "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"

The HTTP method required to make the related call.

customer

Type: object

The details about a customer in PayPal's system of record.

id

Type: string

Pattern: ^[0-9a-zA-Z_-]+$

Min length: 1

Max length: 22

The unique ID for a customer generated by PayPal.

email_address

Type: string

Format: merchant_common_email_address_v2

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])+)\])

Min length: 3

Max length: 254

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.

phone

Type: object

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.

phone_type

Type: string

Enum: "FAX", "HOME", "MOBILE", "OTHER", "PAGER"

The phone type.

phone_numberrequired

Type: object

The phone number, in its canonical international E.164 numbering plan format.

national_numberrequired

Type: string

Pattern: ^[0-9]{1,14}?$

Min length: 1

Max length: 14

merchant_customer_id

Type: string

Pattern: ^[0-9a-zA-Z-_.^*$@#]+$

Min length: 1

Max length: 64

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.

from_request

Type: object

Representation of card details as received in the request.

expiry

Type: string

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$

Min length: 7

Max length: 7

The card expiration year and month, in Internet date format.

last_digits

Type: string

Pattern: [0-9]{2,}

Min length: 2

Max length: 4

The last digits of the payment card.

expiry

Type: string

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$

Min length: 7

Max length: 7

The card expiration year and month, in Internet date format.

bin_details

Type: object

Bank Identification Number (BIN) details used to fund a payment.

bin

Type: string

Pattern: ^[0-9]+$

Min length: 1

Max length: 25

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.

issuing_bank

Type: string

Min length: 1

Max length: 64

The issuer of the card instrument.

bin_country_code

Type: string

Format: ppaas_common_country_code_v2

Pattern: ^([A-Z]{2}|C2)$

Min length: 2

Max length: 2

The two-character ISO-3166-1 country code of the bank.

products

Type: array

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.

Array Items

items

Type: string

Min length: 1

Max length: 255

This value provides the category of the BIN.

stored_credential

Type: object

Provides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:

payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
usage=FIRST is compatible only with payment_initiator=CUSTOMER.
previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.

payment_initiatorrequired

Type: string

Enum: "CUSTOMER", "MERCHANT"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

The person or party who initiated or triggered the payment.

payment_typerequired

Type: string

Enum: "ONE_TIME", "RECURRING", "UNSCHEDULED"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Indicates the type of the stored payment_source payment.

usage

Type: string

Enum: "FIRST", "SUBSEQUENT", "DERIVED"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Default: "DERIVED"

Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

previous_network_transaction_reference

Type: object

Reference values used by the card network to identify a transaction.

idrequired

Type: string

Pattern: ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$

Min length: 9

Max length: 36

Transaction reference id returned by the scheme. For Visa and Amex, this is the "Tran id" field in response. For MasterCard, this is the "BankNet reference id" field in response. For Discover, this is the "NRID" field in response. The pattern we expect for this field from Visa/Amex/CB/Discover is numeric, Mastercard/BNPP is alphanumeric and Paysecure is alphanumeric with special character -.

date

Type: string

Pattern: ^[0-9]+$

Min length: 4

Max length: 4

The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date.

network

Type: string

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"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

Name of the card network through which the transaction was routed.

acquirer_reference_number

Type: string

Pattern: ^[a-zA-Z0-9]+$

Min length: 1

Max length: 36

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

billing_address

Type: object

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1

Type: string

Max length: 300

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.

address_line_2

Type: string

Max length: 300

The second line of the address, for example, a suite or apartment number.

admin_area_2

Type: string

Max length: 120

A city, town, or village. Smaller than admin_area_level_1.

admin_area_1

Type: string

Max length: 300

UK. A county.
US. A state.
Canada. A province.
Japan. A prefecture.
Switzerland. A kanton.

postal_code

Type: string

Max length: 60

The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

country_coderequired

Type: string

Format: ppaas_common_country_code_v2

Pattern: ^([A-Z]{2}|C2)$

Min length: 2

Max length: 2

The 2-character ISO 3166-1 code that identifies the country or region.

currency_code

Type: string

Min length: 3

Max length: 3

Currency code of the given instrument

billing_info

Type: object

The billing details for the subscription. If the subscription was or is active, these fields are populated.

outstanding_balancerequired

Type: object

The total pending bill amount, to be paid by the subscriber.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

cycle_executions

Type: array

The trial and regular billing executions.

Array Items

items

Type: object

The regular and trial execution details for a billing cycle.

tenure_typerequired

Type: string

Enum: "REGULAR", "TRIAL"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The type of the billing cycle.

sequencerequired

Type: integer

Minimum: 0

Maximum: 99

The order in which to run this cycle among other billing cycles.

cycles_completedrequired

Type: integer

Minimum: 0

Maximum: 9999

The number of billing cycles that have completed.

cycles_remaining

Type: integer

Minimum: 0

Maximum: 9999

For a finite billing cycle, cycles_remaining is the number of remaining cycles. For an infinite billing cycle, cycles_remaining is set as 0.

current_pricing_scheme_version

Type: integer

Minimum: 1

Maximum: 99

The active pricing scheme version for the billing cycle.

total_cycles

Type: integer

Minimum: 0

Maximum: 999

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).

last_payment

Type: object

The details for the last payment of the subscription.

amountrequired

Type: object

The last payment amount.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

timerequired

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when the last payment was made, in Internet date and time format.

next_billing_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The next date and time for billing this subscription, in Internet date and time format.

final_payment_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when the final billing cycle occurs, in Internet date and time format.

failed_payments_countrequired

Type: integer

Minimum: 0

Maximum: 999

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.

last_failed_payment

Type: object

The details for the last failed payment of the subscription.

amountrequired

Type: object

The failed payment amount.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

timerequired

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when the failed payment was made, in Internet date and time format.

reason_code

Type: string

Enum:

"PAYMENT_DENIED", "INTERNAL_SERVER_ERROR", "PAYEE_ACCOUNT_RESTRICTED", "PAYER_ACCOUNT_RESTRICTED", "PAYER_CANNOT_PAY", "SENDING_LIMIT_EXCEEDED", "TRANSACTION_RECEIVING_LIMIT_EXCEEDED", "CURRENCY_MISMATCH"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 120

The reason code for the payment failure.

next_payment_retry_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The time when the retry attempt for the failed payment occurs, in Internet date and time format.

create_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

update_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

payer_holding_preference

The payer's holding preference for subscriptions payments.

custom_id

Type: string

Pattern: ^[\x20-\x7E]+

Min length: 1

Max length: 127

The custom id for the subscription. Can be invoice id.

plan_overridden

Type: boolean

Indicates whether the subscription has overridden any plan attributes.

plan

Type: object

The plan details.

product_id

Type: string

Pattern: ^PROD-[A-Z0-9]*$

Min length: 22

Max length: 22

The ID for the product.

name

Type: string

Pattern: ^.*$

Min length: 1

Max length: 127

The plan name.

description

Type: string

Pattern: ^.*$

Min length: 1

Max length: 127

The detailed description of the plan.

billing_cycles

Type: array

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.

Array Items

items

Type: object

The billing cycle details.

pricing_scheme

Type: object

The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.

version

Type: integer

Minimum: 0

Maximum: 999

The version of the pricing scheme.

fixed_price

Type: object

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.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

pricing_model

Type: string

Enum: "VOLUME", "TIERED"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The pricing model for tiered plan. The tiers parameter is required.

tiers

Type: array

An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified.

Array Items

items

Type: object

The pricing tier details.

starting_quantityrequired

Type: string

Pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$

Min length: 1

Max length: 32

The starting quantity for the tier.

ending_quantity

Type: string

Pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$

Min length: 1

Max length: 32

The ending quantity for the tier. Optional for the last tier.

amountrequired

Type: object

The pricing amount for the tier.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

create_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when this pricing scheme was created, in Internet date and time format.

update_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when this pricing scheme was last updated, in Internet date and time format.

frequencyrequired

Type: object

The frequency details for this billing cycle.

interval_unitrequired

Type: string

Enum: "DAY", "WEEK", "MONTH", "YEAR"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The interval at which the subscription is charged or billed.

interval_count

Type: integer

Minimum: 1

Maximum: 365

Default: 1

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

tenure_typerequired

Type: string

Enum: "REGULAR", "TRIAL"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan.

sequencerequired

Type: integer

Minimum: 1

Maximum: 99

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.

total_cycles

Type: integer

Minimum: 0

Maximum: 999

Default: 1

payment_preferences

Type: object

The payment preferences for a subscription.

auto_bill_outstanding

Type: boolean

Default: true

Indicates whether to automatically bill the outstanding amount in the next billing cycle.

setup_fee

Type: object

The initial set-up fee for the service.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

setup_fee_failure_action

Type: string

Enum: "CONTINUE", "CANCEL"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

Default: "CANCEL"

The action to take on the subscription if the initial payment for the setup fails.

payment_failure_threshold

Type: integer

Minimum: 0

Maximum: 999

Default: 0

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.

merchant_preferences

Type: object

The merchant preferences for a subscription.

return_url

Type: string

Format: uri

Min length: 10

Max length: 4000

The URL where the customer is redirected after the customer approves the payment.

cancel_url

Type: string

Format: uri

Min length: 10

Max length: 4000

The URL where the customer is redirected after the customer cancels the payment.

taxes

Type: object

The tax details.

percentagerequired

Type: string

Format: ppaas_common_percentage_v2

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The tax percentage on the billing amount.

inclusive

Type: boolean

Default: true

Indicates whether the tax was already included in the billing amount.

quantity_supported

Type: boolean

Default: false

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

links

Type: array

An array of request-related HATEOAS links.

Array Items

items

Type: object

The request-related HATEOAS link information.

hrefrequired

Type: string

relrequired

Type: string

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

method

Type: string

Enum: "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"

The HTTP method required to make the related call.

Properties

status

Type: string

Enum: "APPROVAL_PENDING", "APPROVED", "ACTIVE", "SUSPENDED", "CANCELLED", "EXPIRED"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The status of the subscription.

status_change_note

Type: string

Pattern: ^.*$

Min length: 1

Max length: 128

The reason or notes for the status of the subscription.

status_update_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

id

Type: string

Min length: 3

Max length: 50

The PayPal-generated ID for the subscription.

plan_id

Type: string

Min length: 3

Max length: 50

The ID of the plan.

start_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

quantity

Type: string

Pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$

Min length: 1

Max length: 32

The quantity of the product in the subscription.

shipping_amount

Type: object

The currency and amount for a financial transaction, such as a balance or payment due.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

subscriber

Type: object

Format: payer_v1

The customer who approves and pays for the order. The customer is also known as the payer.

The subscriber response information.

email_address

Type: string

Format: merchant_common_email_address_v2

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])+)\])

Min length: 3

Max length: 254

The email address of the payer.

payer_id

Type: string

Format: ppaas_payer_id_v3

Pattern: ^[2-9A-HJ-NP-Z]{13}$

Min length: 13

Max length: 13

The PayPal-assigned ID for the payer.

name

Type: object

The name of the party.

given_name

Type: string

Max length: 140

When the party is a person, the party's given, or first, name.

surname

Type: string

Max length: 140

shipping_address

Type: object

The shipping details.

name

Type: object

The name of the party.

full_name

Type: string

Max length: 300

When the party is a person, the party's full name.

email_address

Type: string

Format: ppaas_common_email_address_v2

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])+)\])$

Min length: 3

Max length: 254

The email address of the recipient of the shipped items, which may belong to either the payer, or an alternate contact, for delivery.

phone_number

Type: object

The phone number, in its canonical international E.164 numbering plan format.

country_coderequired

Type: string

Pattern: ^[0-9]{1,3}?$

Min length: 1

Max length: 3

national_numberrequired

Type: string

Pattern: ^[0-9]{1,14}?$

Min length: 1

Max length: 14

type

Type: string

Enum: "SHIPPING", "PICKUP_IN_PERSON", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

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.

options

Type: array

An array of shipping options that the payee or merchant offers to the payer to ship or pick up their items.

Array Items

items

Type: object

The options that the payee or merchant offers to the payer to ship or pick up their items.

idrequired

Type: string

Max length: 127

A unique ID that identifies a payer-selected shipping option.

labelrequired

Type: string

Max length: 127

type

Type: string

Enum: "SHIPPING", "PICKUP", "PICKUP_IN_STORE", "PICKUP_FROM_PERSON"

A classification for the method of purchase fulfillment.

amount

Type: object

The shipping cost for the selected option.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

selectedrequired

Type: boolean

address

Type: object

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1

Type: string

Max length: 300

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.

address_line_2

Type: string

Max length: 300

The second line of the address, for example, a suite or apartment number.

admin_area_2

Type: string

Max length: 120

A city, town, or village. Smaller than admin_area_level_1.

admin_area_1

Type: string

Max length: 300

UK. A county.
US. A state.
Canada. A province.
Japan. A prefecture.
Switzerland. A kanton.

postal_code

Type: string

Max length: 60

The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

country_coderequired

Type: string

Format: ppaas_common_country_code_v2

Pattern: ^([A-Z]{2}|C2)$

Min length: 2

Max length: 2

The 2-character ISO 3166-1 code that identifies the country or region.

payment_source

Type: object

The payment source used to fund the payment.

card

Type: object

The payment card to use to fund a payment. Card can be a credit or debit card.

The payment card used to fund the payment. Card can be a credit or debit card.

name

Type: string

Min length: 2

Max length: 300

The card holder's name as it appears on the card.

last_digits

Type: string

Pattern: [0-9]{2,}

The last digits of the payment card.

brand

Type: string

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"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The card brand or network. Typically used in the response.

available_networks

Type: array

Array of brands or networks associated with the card.

Array Items

items

Type: string

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"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The card network or brand. Applies to credit, debit, gift, and payment cards.

type

Type: string

Enum: "CREDIT", "DEBIT", "PREPAID", "STORE", "UNKNOWN"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The payment card type.

authentication_result

Type: object

Results of Authentication such as 3D Secure.

liability_shift

Type: string

Enum: "NO", "POSSIBLE", "UNKNOWN"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Liability shift indicator. The outcome of the issuer's authentication.

three_d_secure

Type: object

Results of 3D Secure Authentication.

authentication_status

Type: string

Enum: "Y", "N", "U", "A", "C", "R", "D", "I"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

The outcome of the issuer's authentication.

enrollment_status

Type: string

Enum: "Y", "N", "U", "B"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Status of authentication eligibility.

attributes

Type: object

Additional attributes associated with the use of this card.

vault

Type: object

The details about a saved Card payment source.

id

Type: string

Min length: 1

Max length: 255

The PayPal-generated ID for the saved payment source.

status

Type: string

Enum: "VAULTED", "CREATED", "APPROVED"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

The vault status.

links

Type: array

An array of request-related HATEOAS links.

Array Items

items

Type: object

The request-related HATEOAS link information.

hrefrequired

Type: string

relrequired

Type: string

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

method

Type: string

Enum: "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"

The HTTP method required to make the related call.

customer

Type: object

The details about a customer in PayPal's system of record.

id

Type: string

Pattern: ^[0-9a-zA-Z_-]+$

Min length: 1

Max length: 22

The unique ID for a customer generated by PayPal.

email_address

Type: string

Format: merchant_common_email_address_v2

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])+)\])

Min length: 3

Max length: 254

phone

Type: object

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.

phone_type

Type: string

Enum: "FAX", "HOME", "MOBILE", "OTHER", "PAGER"

The phone type.

phone_numberrequired

Type: object

The phone number, in its canonical international E.164 numbering plan format.

national_numberrequired

Type: string

Pattern: ^[0-9]{1,14}?$

Min length: 1

Max length: 14

merchant_customer_id

Type: string

Pattern: ^[0-9a-zA-Z-_.^*$@#]+$

Min length: 1

Max length: 64

from_request

Type: object

Representation of card details as received in the request.

expiry

Type: string

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$

Min length: 7

Max length: 7

The card expiration year and month, in Internet date format.

last_digits

Type: string

Pattern: [0-9]{2,}

Min length: 2

Max length: 4

The last digits of the payment card.

expiry

Type: string

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])$

Min length: 7

Max length: 7

The card expiration year and month, in Internet date format.

bin_details

Type: object

Bank Identification Number (BIN) details used to fund a payment.

bin

Type: string

Pattern: ^[0-9]+$

Min length: 1

Max length: 25

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.

issuing_bank

Type: string

Min length: 1

Max length: 64

The issuer of the card instrument.

bin_country_code

Type: string

Format: ppaas_common_country_code_v2

Pattern: ^([A-Z]{2}|C2)$

Min length: 2

Max length: 2

The two-character ISO-3166-1 country code of the bank.

products

Type: array

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.

Array Items

items

Type: string

Min length: 1

Max length: 255

This value provides the category of the BIN.

stored_credential

Type: object

Provides additional details to process a payment using a card that has been stored or is intended to be stored (also referred to as stored_credential or card-on-file).
Parameter compatibility:

payment_type=ONE_TIME is compatible only with payment_initiator=CUSTOMER.
usage=FIRST is compatible only with payment_initiator=CUSTOMER.
previous_transaction_reference or previous_network_transaction_reference is compatible only with payment_initiator=MERCHANT.
Only one of the parameters - previous_transaction_reference and previous_network_transaction_reference - can be present in the request.

payment_initiatorrequired

Type: string

Enum: "CUSTOMER", "MERCHANT"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

The person or party who initiated or triggered the payment.

payment_typerequired

Type: string

Enum: "ONE_TIME", "RECURRING", "UNSCHEDULED"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Indicates the type of the stored payment_source payment.

usage

Type: string

Enum: "FIRST", "SUBSEQUENT", "DERIVED"

Pattern: ^[0-9A-Z_]+$

Min length: 1

Max length: 255

Default: "DERIVED"

Indicates if this is a first or subsequent payment using a stored payment source (also referred to as stored credential or card on file).

previous_network_transaction_reference

Type: object

Reference values used by the card network to identify a transaction.

idrequired

Type: string

Pattern: ^[a-zA-Z0-9-_@.:&+=*^'~#!$%()]+$

Min length: 9

Max length: 36

date

Type: string

Pattern: ^[0-9]+$

Min length: 4

Max length: 4

The date that the transaction was authorized by the scheme. This field may not be returned for all networks. MasterCard refers to this field as "BankNet reference date.

network

Type: string

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"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

Name of the card network through which the transaction was routed.

acquirer_reference_number

Type: string

Pattern: ^[a-zA-Z0-9]+$

Min length: 1

Max length: 36

Reference ID issued for the card transaction. This ID can be used to track the transaction across processors, card brands and issuing banks.

billing_address

Type: object

The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.

address_line_1

Type: string

Max length: 300

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.

address_line_2

Type: string

Max length: 300

The second line of the address, for example, a suite or apartment number.

admin_area_2

Type: string

Max length: 120

A city, town, or village. Smaller than admin_area_level_1.

admin_area_1

Type: string

Max length: 300

UK. A county.
US. A state.
Canada. A province.
Japan. A prefecture.
Switzerland. A kanton.

postal_code

Type: string

Max length: 60

The postal code, which is the ZIP code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code.

country_coderequired

Type: string

Format: ppaas_common_country_code_v2

Pattern: ^([A-Z]{2}|C2)$

Min length: 2

Max length: 2

The 2-character ISO 3166-1 code that identifies the country or region.

currency_code

Type: string

Min length: 3

Max length: 3

Currency code of the given instrument

billing_info

Type: object

The billing details for the subscription. If the subscription was or is active, these fields are populated.

outstanding_balancerequired

Type: object

The total pending bill amount, to be paid by the subscriber.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

cycle_executions

Type: array

The trial and regular billing executions.

Array Items

items

Type: object

The regular and trial execution details for a billing cycle.

tenure_typerequired

Type: string

Enum: "REGULAR", "TRIAL"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The type of the billing cycle.

sequencerequired

Type: integer

Minimum: 0

Maximum: 99

The order in which to run this cycle among other billing cycles.

cycles_completedrequired

Type: integer

Minimum: 0

Maximum: 9999

The number of billing cycles that have completed.

cycles_remaining

Type: integer

Minimum: 0

Maximum: 9999

For a finite billing cycle, cycles_remaining is the number of remaining cycles. For an infinite billing cycle, cycles_remaining is set as 0.

current_pricing_scheme_version

Type: integer

Minimum: 1

Maximum: 99

The active pricing scheme version for the billing cycle.

total_cycles

Type: integer

Minimum: 0

Maximum: 999

last_payment

Type: object

The details for the last payment of the subscription.

amountrequired

Type: object

The last payment amount.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

timerequired

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when the last payment was made, in Internet date and time format.

next_billing_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The next date and time for billing this subscription, in Internet date and time format.

final_payment_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when the final billing cycle occurs, in Internet date and time format.

failed_payments_countrequired

Type: integer

Minimum: 0

Maximum: 999

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.

last_failed_payment

Type: object

The details for the last failed payment of the subscription.

amountrequired

Type: object

The failed payment amount.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

timerequired

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when the failed payment was made, in Internet date and time format.

reason_code

Type: string

Enum:

"PAYMENT_DENIED", "INTERNAL_SERVER_ERROR", "PAYEE_ACCOUNT_RESTRICTED", "PAYER_ACCOUNT_RESTRICTED", "PAYER_CANNOT_PAY", "SENDING_LIMIT_EXCEEDED", "TRANSACTION_RECEIVING_LIMIT_EXCEEDED", "CURRENCY_MISMATCH"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 120

The reason code for the payment failure.

next_payment_retry_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The time when the retry attempt for the failed payment occurs, in Internet date and time format.

create_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

update_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.

payer_holding_preference

The payer's holding preference for subscriptions payments.

custom_id

Type: string

Pattern: ^[\x20-\x7E]+

Min length: 1

Max length: 127

The custom id for the subscription. Can be invoice id.

plan_overridden

Type: boolean

Indicates whether the subscription has overridden any plan attributes.

plan

Type: object

The plan details.

product_id

Type: string

Pattern: ^PROD-[A-Z0-9]*$

Min length: 22

Max length: 22

The ID for the product.

name

Type: string

Pattern: ^.*$

Min length: 1

Max length: 127

The plan name.

description

Type: string

Pattern: ^.*$

Min length: 1

Max length: 127

The detailed description of the plan.

billing_cycles

Type: array

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.

Array Items

items

Type: object

The billing cycle details.

pricing_scheme

Type: object

The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.

version

Type: integer

Minimum: 0

Maximum: 999

The version of the pricing scheme.

fixed_price

Type: object

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

pricing_model

Type: string

Enum: "VOLUME", "TIERED"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The pricing model for tiered plan. The tiers parameter is required.

tiers

Type: array

An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified.

Array Items

items

Type: object

The pricing tier details.

starting_quantityrequired

Type: string

Pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$

Min length: 1

Max length: 32

The starting quantity for the tier.

ending_quantity

Type: string

Pattern: ^([0-9]+|([0-9]+)?[.][0-9]+)$

Min length: 1

Max length: 32

The ending quantity for the tier. Optional for the last tier.

amountrequired

Type: object

The pricing amount for the tier.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

create_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when this pricing scheme was created, in Internet date and time format.

update_time

Type: string

Format: ppaas_date_time_v3

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})$

Min length: 20

Max length: 64

The date and time when this pricing scheme was last updated, in Internet date and time format.

frequencyrequired

Type: object

The frequency details for this billing cycle.

interval_unitrequired

Type: string

Enum: "DAY", "WEEK", "MONTH", "YEAR"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The interval at which the subscription is charged or billed.

interval_count

Type: integer

Minimum: 1

Maximum: 365

Default: 1

`Interval unit`	Maximum interval count
`DAY`	365
`WEEK`	52
`MONTH`	12
`YEAR`	1

tenure_typerequired

Type: string

Enum: "REGULAR", "TRIAL"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan.

sequencerequired

Type: integer

Minimum: 1

Maximum: 99

total_cycles

Type: integer

Minimum: 0

Maximum: 999

Default: 1

payment_preferences

Type: object

The payment preferences for a subscription.

auto_bill_outstanding

Type: boolean

Default: true

Indicates whether to automatically bill the outstanding amount in the next billing cycle.

setup_fee

Type: object

The initial set-up fee for the service.

currency_coderequired

Type: string

Min length: 3

Max length: 3

The three-character ISO-4217 currency code that identifies the currency.

valuerequired

Type: string

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

Max length: 32

The value, which might be:

An integer for currencies like JPY that are not typically fractional.
A decimal fraction for currencies like TND that are subdivided into thousandths.

For the required number of decimal places for a currency code, see Currency Codes.

setup_fee_failure_action

Type: string

Enum: "CONTINUE", "CANCEL"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

Default: "CANCEL"

The action to take on the subscription if the initial payment for the setup fails.

payment_failure_threshold

Type: integer

Minimum: 0

Maximum: 999

Default: 0

merchant_preferences

Type: object

The merchant preferences for a subscription.

return_url

Type: string

Format: uri

Min length: 10

Max length: 4000

The URL where the customer is redirected after the customer approves the payment.

cancel_url

Type: string

Format: uri

Min length: 10

Max length: 4000

The URL where the customer is redirected after the customer cancels the payment.

taxes

Type: object

The tax details.

percentagerequired

Type: string

Format: ppaas_common_percentage_v2

Pattern: ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$

The tax percentage on the billing amount.

inclusive

Type: boolean

Default: true

Indicates whether the tax was already included in the billing amount.

quantity_supported

Type: boolean

Default: false

Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.

links

Type: array

An array of request-related HATEOAS links.

Array Items

items

Type: object

The request-related HATEOAS link information.

hrefrequired

Type: string

relrequired

Type: string

The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations.

method

Type: string

Enum: "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH"

The HTTP method required to make the related call.

subscription

Schema Information

Properties

On this page

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more

subscription

Schema Information

Properties