Create Subscription Request

The create subscription request details.

Schema Information

Type:object

Properties

plan_idrequired

Type: string

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

Min length: 26

Max length: 26

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

Default: "Current time"

The date and time when the subscription started, in Internet date and time format.

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 shipping charges.

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

phone

Type: object

The phone number of the customer. Available only when you enable the Contact Telephone Number option in the Profile & Settings for the merchant's PayPal account. The phone.phone_number supports only national_number.

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

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

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

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.

Note: The country code for Great Britain is GB and not UK as 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.

payment_source

Type: object

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.

card

Type: object

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

name

Type: string

Pattern: ^.{1,300}$

Min length: 1

Max length: 300

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

number

Type: string

Pattern: ^[0-9]{13,19}$

Min length: 13

Max length: 19

The primary account number (PAN) for 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 For example: 2028-04

security_code

Type: string

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

Min length: 3

Max length: 4

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.

type

Type: string

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

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The payment card type.

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.

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.

Note: The country code for Great Britain is GB and not UK as 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.

attributes

Type: object

Additional attributes associated with the use of this card.

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.

vault

Type: object

Instruction to vault the card based on the specified strategy.

store_in_vault

Type: string

Enum: "ON_SUCCESS"

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

Min length: 1

Max length: 255

Defines how and when the payment source gets vaulted.

verification

Type: object

Instruction to optionally verify the card based on the specified strategy.

method

Type: string

Enum: "SCA_ALWAYS", "SCA_WHEN_REQUIRED", "3D_SECURE", "AVS_CVV"

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

Min length: 1

Max length: 255

Default: "SCA_WHEN_REQUIRED"

The method used for card verification.

auto_renewal

Type: boolean

Default: false

DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.

application_context

Type: object

DEPRECATED. The application context, which customizes the payer experience during the subscription approval process with PayPal.

brand_name

Type: string

Pattern: ^.*$

Min length: 1

Max length: 127

The label that overrides the business name in the PayPal account on the PayPal site.

locale

Type: string

Format: ppaas_common_language_v3

Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$

Min length: 2

Max length: 10

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.

shipping_preference

Type: string

Enum: "GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

Default: "GET_FROM_FILE"

The location from which the shipping address is derived.

user_action

Type: string

Enum: "CONTINUE", "SUBSCRIBE_NOW"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

Default: "SUBSCRIBE_NOW"

Configures the label name to Continue or Subscribe Now for subscription consent experience.

payment_method

Type: object

The customer and merchant payment preferences.

payee_preferred

Type: string

Enum: "UNRESTRICTED", "IMMEDIATE_PAYMENT_REQUIRED"

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

Min length: 1

Max length: 255

Default: "UNRESTRICTED"

The merchant-preferred payment methods.

return_urlrequired

Type: string

Format: uri

Min length: 10

Max length: 4000

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

cancel_urlrequired

Type: string

Format: uri

Min length: 10

Max length: 4000

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

custom_id

Type: string

Pattern: ^[\x20-\x7E]+

Min length: 1

Max length: 127

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

plan

Type: object

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.

billing_cycles

Type: array

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.

Array Items

items

Type: object

The billing cycle details to override at subscription level. The subscription billing cycle definition has to adhere to the plan billing cycle definition.

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.

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

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

payment_preferences

Type: object

The payment preferences to override at subscription level.

auto_bill_outstanding

Type: boolean

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

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

payment_failure_threshold

Type: integer

Minimum: 0

Maximum: 999

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.

taxes

Type: object

The tax details.

percentage

Type: string

Format: ppaas_common_percentage_v2

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

The tax percentage on the billing amount.

inclusive

Type: boolean

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

merchant_inventory

Merchant's inventory identifier details for the WPS hosted button.

Properties

plan_idrequired

Type: string

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

Min length: 26

Max length: 26

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

Default: "Current time"

The date and time when the subscription started, in Internet date and time format.

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 shipping charges.

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 request 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

phone

Type: object

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

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.

Note: The country code for Great Britain is GB and not UK as 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.

payment_source

Type: object

card

Type: object

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

name

Type: string

Pattern: ^.{1,300}$

Min length: 1

Max length: 300

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

number

Type: string

Pattern: ^[0-9]{13,19}$

Min length: 13

Max length: 19

The primary account number (PAN) for 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 For example: 2028-04

security_code

Type: string

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

Min length: 3

Max length: 4

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.

type

Type: string

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

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 255

The payment card type.

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.

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.

Note: The country code for Great Britain is GB and not UK as 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.

attributes

Type: object

Additional attributes associated with the use of this card.

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

vault

Type: object

Instruction to vault the card based on the specified strategy.

store_in_vault

Type: string

Enum: "ON_SUCCESS"

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

Min length: 1

Max length: 255

Defines how and when the payment source gets vaulted.

verification

Type: object

Instruction to optionally verify the card based on the specified strategy.

method

Type: string

Enum: "SCA_ALWAYS", "SCA_WHEN_REQUIRED", "3D_SECURE", "AVS_CVV"

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

Min length: 1

Max length: 255

Default: "SCA_WHEN_REQUIRED"

The method used for card verification.

auto_renewal

Type: boolean

Default: false

DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.

application_context

Type: object

DEPRECATED. The application context, which customizes the payer experience during the subscription approval process with PayPal.

brand_name

Type: string

Pattern: ^.*$

Min length: 1

Max length: 127

The label that overrides the business name in the PayPal account on the PayPal site.

locale

Type: string

Format: ppaas_common_language_v3

Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}|[0-9]{3}))?$

Min length: 2

Max length: 10

shipping_preference

Type: string

Enum: "GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

Default: "GET_FROM_FILE"

The location from which the shipping address is derived.

user_action

Type: string

Enum: "CONTINUE", "SUBSCRIBE_NOW"

Pattern: ^[A-Z_]+$

Min length: 1

Max length: 24

Default: "SUBSCRIBE_NOW"

Configures the label name to Continue or Subscribe Now for subscription consent experience.

payment_method

Type: object

The customer and merchant payment preferences.

payee_preferred

Type: string

Enum: "UNRESTRICTED", "IMMEDIATE_PAYMENT_REQUIRED"

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

Min length: 1

Max length: 255

Default: "UNRESTRICTED"

The merchant-preferred payment methods.

return_urlrequired

Type: string

Format: uri

Min length: 10

Max length: 4000

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

cancel_urlrequired

Type: string

Format: uri

Min length: 10

Max length: 4000

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

custom_id

Type: string

Pattern: ^[\x20-\x7E]+

Min length: 1

Max length: 127

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

plan

Type: object

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.

billing_cycles

Type: array

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.

Array Items

items

Type: object

The billing cycle details to override at subscription level. The subscription billing cycle definition has to adhere to the plan billing cycle definition.

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.

sequencerequired

Type: integer

Minimum: 1

Maximum: 99

total_cycles

Type: integer

Minimum: 0

Maximum: 999

payment_preferences

Type: object

The payment preferences to override at subscription level.

auto_bill_outstanding

Type: boolean

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

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

payment_failure_threshold

Type: integer

Minimum: 0

Maximum: 999

taxes

Type: object

The tax details.

percentage

Type: string

Format: ppaas_common_percentage_v2

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

The tax percentage on the billing amount.

inclusive

Type: boolean

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

merchant_inventory

Merchant's inventory identifier details for the WPS hosted button.

Create Subscription Request

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

Create Subscription Request

Schema Information

Properties