Subscriptions (1)

You can use billing plans and subscriptions to create subscriptions that process recurring PayPal payments for physical or digital goods, or services. A plan includes pricing and billing cycle information that defines the amount and frequency of charge for a subscription. You can also define a fixed plan, such as a $5 basic plan or a volume- or graduated-based plan with pricing tiers based on the quantity purchased. For more information, see Subscriptions Overview.

Create plan

post/v1/billing/plans

Creates a plan that defines pricing and billing cycle details for subscriptions.

SecurityOauth2
Request
header Parameters
Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

PayPal-Request-Id
string

The server stores keys for 72 hours.

Request Body schema:
product_id
required
string = 22 characters ^PROD-[A-Z0-9]*$

The ID of the product created through Catalog Products API.

name
required
string [ 1 .. 127 ] characters ^.*$

The plan name.

status
string [ 1 .. 24 ] characters ^[A-Z_]+$
Default: "ACTIVE"

The initial state of the plan. Allowed input values are CREATED and ACTIVE.

Enum Value Description
CREATED

The plan was created. You cannot create subscriptions for a plan in this state.

INACTIVE

The plan is inactive.

ACTIVE

The plan is active. You can only create subscriptions for a plan in this state.

description
string [ 1 .. 127 ] characters ^.*$

The detailed description of the plan.

required
Array of objects (billing_cycle) [ 1 .. 12 ] items

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.

quantity_supported
boolean
Default: false

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

required
object (payment_preferences)

The payment preferences for a subscription.

object (taxes)

The tax details.

Responses
201

A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing plan details.

Request samples
{
  • "product_id": "PROD-XXCD1234QWER65782",
  • "name": "Video Streaming Service Plan",
  • "description": "Video Streaming Service basic plan",
  • "status": "ACTIVE",
  • "billing_cycles": [
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 1,
      • "total_cycles": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "3",
          • "currency_code": "USD"
          }
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 2,
      • "total_cycles": 3,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "6",
          • "currency_code": "USD"
          }
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "REGULAR",
      • "sequence": 3,
      • "total_cycles": 12,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "10",
          • "currency_code": "USD"
          }
        }
      }
    ],
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee": {
      • "value": "10",
      • "currency_code": "USD"
      },
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 3
    },
  • "taxes": {
    • "percentage": "10",
    • "inclusive": false
    }
}
Response samples
application/json
{
  • "id": "P-5ML4271244454362WXNWU5NQ",
  • "product_id": "PROD-XXCD1234QWER65782",
  • "name": "Video Streaming Service Plan",
  • "description": "Video Streaming Service basic plan",
  • "status": "ACTIVE",
  • "billing_cycles": [
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 1,
      • "total_cycles": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "3",
          • "currency_code": "USD"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 2,
      • "total_cycles": 3,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "6"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "REGULAR",
      • "sequence": 3,
      • "total_cycles": 12,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "10"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      }
    ],
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee": {
      • "value": "10",
      • "currency_code": "USD"
      },
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 3
    },
  • "taxes": {
    • "percentage": "10",
    • "inclusive": false
    },
  • "create_time": "2020-05-27T12:13:51Z",
  • "update_time": "2020-05-27T12:13:51Z",
  • "links": []
}

List plans

get/v1/billing/plans

Lists billing plans.

SecurityOauth2
Request
query Parameters
product_id
string [ 6 .. 50 ] characters

Filters the response by a Product ID.

page_size
integer [ 1 .. 20 ]
Default: 10

The number of items to return in the response.

page
integer [ 1 .. 100000 ]
Default: 1

A non-zero integer which is the start index of the entire list of items to return in the response. The combination of page=1 and page_size=20 returns the first 20 items. The combination of page=2 and page_size=20 returns the next 20 items.

total_required
boolean
Default: false

Indicates whether to show the total count in the response.

header Parameters
Prefer
string
Default: return=minimal

The preferred server response upon successful completion of the request. Value is:

  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, name, description and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.

Request Body schema:
any
Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that lists billing plans.

Request samples
{ }
Response samples
application/json
{}

Show plan details

get/v1/billing/plans/{id}

Shows details for a plan, by ID.

SecurityOauth2
Request
path Parameters
id
required
string

The ID of the plan.

Responses
200

A successful request returns the HTTP 200 OK status code and a JSON response body that shows plan details.

Request samples 
Response samples 
application/json
{
  • "id": "P-5ML4271244454362WXNWU5NQ",
  • "product_id": "PROD-XXCD1234QWER65782",
  • "name": "Basic Plan",
  • "description": "Basic Plan",
  • "status": "ACTIVE",
  • "billing_cycles": [
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 1,
      • "total_cycles": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "3"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "TRIAL",
      • "sequence": 2,
      • "total_cycles": 3,
      • "pricing_scheme": {
        • "fixed_price": {
          • "currency_code": "USD",
          • "value": "6"
          },
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      },
    • {
      • "frequency": {
        • "interval_unit": "MONTH",
        • "interval_count": 1
        },
      • "tenure_type": "REGULAR",
      • "sequence": 3,
      • "total_cycles": 12,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "10",
          • "currency_code": "USD"
          },
        • "status": "ACTIVE",
        • "version": 1,
        • "create_time": "2020-05-27T12:13:51Z",
        • "update_time": "2020-05-27T12:13:51Z"
        }
      }
    ],
  • "taxes": {
    • "percentage": "10",
    • "inclusive": false
    },
  • "create_time": "2020-05-27T12:13:51Z",
  • "update_time": "2020-05-27T12:13:51Z",
  • "links": []
}
Update plan
patch/v1/billing/plans/{id}
Updates a plan with the CREATED or ACTIVE status. For an INACTIVE plan, you can make only status updates.
You can patch these attributes and objects:
Attribute or objectOperations
descriptionreplace
payment_preferences.auto_bill_outstandingreplace
taxes.percentagereplace
payment_preferences.payment_failure_thresholdreplace
payment_preferences.setup_feereplace
payment_preferences.setup_fee_failure_actionreplace
namereplace


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the plan.


 
Request Body schema: application/json
 Array 
op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
object (Patch Value) 
The value to apply. The remove operation does not require a value.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
application/json
[
  • {
    • "op": "replace",
    • "path": "/payment_preferences/payment_failure_threshold",
    • "value": 7
    },
  • {
    • "op": "replace",
    • "path": "/name",
    • "value": "Updated Video Streaming Service Plan"
    }
]
Response samples 
application/json
{ }
Activate plan
post/v1/billing/plans/{id}/activate
Activates a plan, by ID.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the plan.


 
Request Body schema: 
any
 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
{ }
Response samples 
application/json
{ }
Deactivate plan
post/v1/billing/plans/{id}/deactivate
Deactivates a plan, by ID.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the plan.


 
Request Body schema: 
any
 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
{ }
Response samples 
application/json
{ }
Update pricing
post/v1/billing/plans/{id}/update-pricing-schemes
Updates pricing for a plan. For example, you can update a regular billing cycle from $5 per month to $7 per month.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID for the plan.


 
Request Body schema: 
required
Array of objects (update_pricing_scheme_request)   [ 1 .. 99 ] items 
An array of pricing schemes.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
{
  • "pricing_schemes": [
    • {
      • "billing_cycle_sequence": 1,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "50",
          • "currency_code": "USD"
          }
        }
      },
    • {
      • "billing_cycle_sequence": 2,
      • "pricing_scheme": {
        • "fixed_price": {
          • "value": "100",
          • "currency_code": "USD"
          },
        • "pricing_model": "VOLUME",
        • "tiers": [
          • {
            • "starting_quantity": "1",
            • "ending_quantity": "1000",
            • "amount": {
              • "value": "150",
              • "currency_code": "USD"
              }
            },
          • {
            • "starting_quantity": "1001",
            • "amount": {
              • "value": "250",
              • "currency_code": "USD"
              }
            }
          ]
        }
      }
    ]
}
Response samples 
application/json
{ }
Create subscription
post/v1/billing/subscriptions
Creates a subscription.


SecurityOauth2 
Request 
header Parameters
Prefer
string
 Default:  return=minimal
The preferred server response upon successful completion of the request. Value is:
  • return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.
  • return=representation. The server returns a complete resource representation, including the current state of the resource.


 
PayPal-Request-Id
string
The server stores keys for 72 hours.


 
Request Body schema: 
plan_id
required
string  = 26 characters ^P-[A-Z0-9]*$
The ID of the plan.


 
quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The quantity of the product in the subscription.


 
auto_renewal
boolean
 Default:  false
DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.


 
custom_id
string  [ 1 .. 127 ] characters ^[\x20-\x7E]+
The custom id for the subscription. Can be invoice id.


 
start_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
 Default:  "Current time"
The date and time when the subscription started, in Internet date and time format.


 
object (Money) 
The shipping charges.


 
object <payer_v1>  (subscriber_request) 
The subscriber request information .


 
object (application_context) 
The application context, which customizes the payer experience during the subscription approval process with PayPal.


 
object (plan_override) 
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.


 
Responses 
201
A successful request returns the HTTP 201 Created status code and a JSON response body that shows subscription details.


Request samples 
{
  • "plan_id": "P-5ML4271244454362WXNWU5NQ",
  • "start_time": "2018-11-01T00:00:00Z",
  • "quantity": "20",
  • "shipping_amount": {
    • "currency_code": "USD",
    • "value": "10.00"
    },
  • "subscriber": {
    • "name": {
      • "given_name": "John",
      • "surname": "Doe"
      },
    • "email_address": "customer@example.com",
    • "shipping_address": {
      • "name": {
        • "full_name": "John Doe"
        },
      • "address": {
        • "address_line_1": "2211 N First Street",
        • "address_line_2": "Building 17",
        • "admin_area_2": "San Jose",
        • "admin_area_1": "CA",
        • "postal_code": "95131",
        • "country_code": "US"
        }
      }
    },
  • "application_context": {
    • "brand_name": "walmart",
    • "locale": "en-US",
    • "shipping_preference": "SET_PROVIDED_ADDRESS",
    • "user_action": "SUBSCRIBE_NOW",
    • "payment_method": {
      • "payer_selected": "PAYPAL",
      • "payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
      },
    • "return_url": "https://example.com/returnUrl",
    • "cancel_url": "https://example.com/cancelUrl"
    }
}
Response samples 
application/json
{}
Show subscription details
get/v1/billing/subscriptions/{id}
Shows details for a subscription, by ID.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the subscription.


 
query Parameters
fields
string  [ 1 .. 100 ] characters 
List of fields that are to be returned in the response. Possible value for fields are last_failed_payment and plan.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows subscription details.


Request samples 
Response samples 
application/json
{
  • "id": "I-BW452GLLEP1G",
  • "plan_id": "P-5ML4271244454362WXNWU5NQ",
  • "start_time": "2019-04-10T07:00:00Z",
  • "quantity": "20",
  • "shipping_amount": {
    • "currency_code": "USD",
    • "value": "10.0"
    },
  • "subscriber": {
    • "shipping_address": {
      • "name": {
        • "full_name": "John Doe"
        },
      • "address": {
        • "address_line_1": "2211 N First Street",
        • "address_line_2": "Building 17",
        • "admin_area_2": "San Jose",
        • "admin_area_1": "CA",
        • "postal_code": "95131",
        • "country_code": "US"
        }
      },
    • "name": {
      • "given_name": "John",
      • "surname": "Doe"
      },
    • "email_address": "customer@example.com",
    • "payer_id": "2BBBB8YJQSCCC"
    },
  • "billing_info": {
    • "outstanding_balance": {
      • "currency_code": "USD",
      • "value": "1.0"
      },
    • "cycle_executions": [
      • {
        • "tenure_type": "TRIAL",
        • "sequence": 1,
        • "cycles_completed": 0,
        • "cycles_remaining": 2,
        • "total_cycles": 2
        },
      • {
        • "tenure_type": "TRIAL",
        • "sequence": 2,
        • "cycles_completed": 0,
        • "cycles_remaining": 3,
        • "total_cycles": 3
        },
      • {
        • "tenure_type": "REGULAR",
        • "sequence": 3,
        • "cycles_completed": 0,
        • "cycles_remaining": 12,
        • "total_cycles": 12
        }
      ],
    • "last_payment": {
      • "amount": {
        • "currency_code": "USD",
        • "value": "1.15"
        },
      • "time": "2019-04-09T10:27:20Z"
      },
    • "next_billing_time": "2019-04-10T10:00:00Z",
    • "failed_payments_count": 0
    },
  • "create_time": "2019-04-09T10:26:04Z",
  • "update_time": "2019-04-09T10:27:27Z",
  • "links": [],
  • "status": "ACTIVE",
  • "status_update_time": "2019-04-09T10:27:27Z"
}
Update subscription
patch/v1/billing/subscriptions/{id}
Updates a subscription which could be in ACTIVE or SUSPENDED status. You can override plan level default attributes by providing customised values for plan path in the patch request.
 
     
  • You cannot update attributes that have already completed (Example - trial cycles can’t be updated if completed).
    •  
  • Once overridden, changes to plan resource will not impact subscription.
    •  
  • Any price update will not impact billing cycles within next 10 days (Applicable only for subscriptions funded by PayPal account).
    •  
 Following are the fields eligible for patch.
Attribute or objectOperations
billing_info.outstanding_balancereplace
custom_idadd,replace
plan.billing_cycles[@sequence==n].
pricing_scheme.fixed_price		add,replace
plan.billing_cycles[@sequence==n].
pricing_scheme.tiers		replace
plan.billing_cycles[@sequence==n].
total_cycles		replace
plan.payment_preferences.
auto_bill_outstanding		replace
plan.payment_preferences.
payment_failure_threshold		replace
plan.taxes.inclusiveadd,replace
plan.taxes.percentageadd,replace
shipping_amountadd,replace
start_timereplace
subscriber.shipping_addressadd,replace
subscriber.payment_source (for subscriptions funded
by card payments)		replace


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID for the subscription.


 
Request Body schema: application/json
 Array 
op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
object (Patch Value) 
The value to apply. The remove operation does not require a value.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
application/json
[
  • {
    • "op": "replace",
    • "path": "/plan/billing_cycles/@sequence==1/pricing_scheme/fixed_price",
    • "value": {
      • "currency_code": "USD",
      • "value": "50.00"
      }
    },
  • {
    • "op": "replace",
    • "path": "/plan/billing_cycles/@sequence==2/pricing_scheme/tiers",
    • "value": [
      • {
        • "starting_quantity": "1",
        • "ending_quantity": "1000",
        • "amount": {
          • "value": "500",
          • "currency_code": "USD"
          }
        },
      • {
        • "starting_quantity": "1001",
        • "amount": {
          • "value": "2000",
          • "currency_code": "USD"
          }
        }
      ]
    },
  • {
    • "op": "replace",
    • "path": "/plan/payment_preferences/auto_bill_outstanding",
    • "value": true
    },
  • {
    • "op": "replace",
    • "path": "/plan/payment_preferences/payment_failure_threshold",
    • "value": 1
    },
  • {
    • "op": "replace",
    • "path": "/plan/taxes/percentage",
    • "value": "10"
    }
]
Response samples 
application/json
{ }
Revise plan or quantity of subscription
post/v1/billing/subscriptions/{id}/revise
Updates the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the shipping_amount, shipping_address values for the subscription. This type of update requires the buyer's consent.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the subscription.


 
Request Body schema: 
plan_id
string  = 26 characters ^P-[A-Z0-9]*$
The unique PayPal-generated ID for the plan.


 
quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The quantity of the product or service in the subscription.


 
object (Money) 
The shipping charges.


 
object (shipping_detail) 
The shipping address of the subscriber.


 
object (application_context) 
The application context, which customizes the payer experience during the subscription approval process with PayPal.


 
object (plan_override) 
An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object. Any existing overrides will not be carried forward during subscription revise.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows subscription details.


Request samples 
{
  • "plan_id": "P-5ML4271244454362WXNWU5NQ",
  • "shipping_amount": {
    • "currency_code": "USD",
    • "value": "10.00"
    },
  • "shipping_address": {
    • "name": {
      • "full_name": "John Doe"
      },
    • "address": {
      • "address_line_1": "2211 N First Street",
      • "address_line_2": "Building 17",
      • "admin_area_2": "San Jose",
      • "admin_area_1": "CA",
      • "postal_code": "95131",
      • "country_code": "US"
      }
    },
  • "application_context": {}
}
Response samples 
application/json
{}
Suspend subscription
post/v1/billing/subscriptions/{id}/suspend
Suspends the subscription.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the subscription.


 
Request Body schema: 
reason
required
string  [ 1 .. 128 ] characters ^.*$
The reason for suspension of the Subscription.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
{
  • "reason": "Item out of stock"
}
Response samples 
application/json
{ }
Cancel subscription
post/v1/billing/subscriptions/{id}/cancel
Cancels the subscription.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the subscription.


 
Request Body schema: 
reason
required
string  [ 1 .. 128 ] characters ^.*$
The reason for the cancellation of a subscription.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
{
  • "reason": "Not satisfied with the service"
}
Response samples 
application/json
{ }
Activate subscription
post/v1/billing/subscriptions/{id}/activate
Activates the subscription.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the subscription.


 
Request Body schema: 
reason
string  [ 1 .. 128 ] characters ^.*$
The reason for activation of a subscription. Required to reactivate the subscription.


 
Responses 
204
A successful request returns the HTTP 204 No Content status code with no JSON response body.


Request samples 
{
  • "reason": "Reactivating the subscription"
}
Response samples 
application/json
{ }
Capture authorized payment on subscription
post/v1/billing/subscriptions/{id}/capture
Captures an authorized payment from the subscriber on the subscription.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the subscription.


 
header Parameters
PayPal-Request-Id
string
The server stores keys for 72 hours.


 
Request Body schema: 
note
required
string  [ 1 .. 128 ] characters ^.*$
The reason or note for the subscription charge.


 
capture_type
required
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The type of capture.


 Value Description
OUTSTANDING_BALANCE
The outstanding balance that the subscriber must clear.


 
required
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
Responses 
202
Request Accepted.


Request samples 
{
  • "note": "Charging as the balance reached the limit",
  • "capture_type": "OUTSTANDING_BALANCE",
  • "amount": {
    • "currency_code": "USD",
    • "value": "100"
    }
}
Response samples 
application/json
{ }
List transactions for subscription
get/v1/billing/subscriptions/{id}/transactions
Lists transactions for a subscription.


SecurityOauth2 
Request 
path Parameters
id
required
string
The ID of the subscription.


 
query Parameters
start_time
required
string <ppaas_date_time_v3>   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The start time of the range of transactions to list.


 
end_time
required
string <ppaas_date_time_v3>   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The end time of the range of transactions to list.


 
Responses 
200
A successful request returns the HTTP 200 OK status code and a JSON response body that shows subscription details.


Request samples 
Response samples 
application/json
{
  • "transactions": [
    • {
      • "id": "TRFGHNJKOIIOJKL",
      • "status": "COMPLETED",
      • "payer_email": "customer@example.com",
      • "payer_name": {
        • "given_name": "John",
        • "surname": "Doe"
        },
      • "amount_with_breakdown": {
        • "gross_amount": {
          • "currency_code": "USD",
          • "value": "10.00"
          },
        • "fee_amount": {
          • "currency_code": "USD",
          • "value": "1.00"
          },
        • "net_amount": {
          • "currency_code": "USD",
          • "value": "9.00"
          }
        },
      • "time": "2018-03-16T07:40:20.940Z"
      },
    • {
      • "id": "VDFG45345FFGS",
      • "status": "COMPLETED",
      • "payer_email": "customer2@example.com",
      • "payer_name": {
        • "given_name": "Jhonny",
        • "surname": "Cat"
        },
      • "amount_with_breakdown": {
        • "gross_amount": {
          • "currency_code": "USD",
          • "value": "15.00"
          },
        • "fee_amount": {
          • "currency_code": "USD",
          • "value": "1.00"
          },
        • "net_amount": {
          • "currency_code": "USD",
          • "value": "14.00"
          }
        },
      • "time": "2018-08-21T07:50:20.940Z"
      }
    ],
  • "links": []
}
Definitions
amount_with_breakdown
The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.


required
object (Money) 
The amount for this transaction.


 
object (Money) 
The item total for the transaction.


 
object (Money) 
The fee details for the transaction.


 
object (Money) 
The shipping amount for the transaction.


 
object (Money) 
The tax amount for the transaction.


 
object (Money) 
The net amount that the payee receives for this transaction in their PayPal account. The net amount is computed as gross_amount minus the paypal_fee.


 
{
  • "gross_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "total_item_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "fee_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "tax_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "net_amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
application_context
The application context, which customizes the payer experience during the subscription approval process with PayPal.


brand_name
string  [ 1 .. 127 ] characters ^.*$
The label that overrides the business name in the PayPal account on the PayPal site.


 
shipping_preference
string  [ 1 .. 24 ] characters ^[A-Z_]+$
 Default:  "GET_FROM_FILE"
The location from which the shipping address is derived.


 Enum Value Description
GET_FROM_FILE
Get the customer-provided shipping address on the PayPal site.


NO_SHIPPING
Redacts the shipping address from the PayPal site. Recommended for digital goods.


SET_PROVIDED_ADDRESS
Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages.


 
user_action
string  [ 1 .. 24 ] characters ^[A-Z_]+$
 Default:  "SUBSCRIBE_NOW"
Configures the label name to Continue or Subscribe Now for subscription consent experience.


 Enum Value Description
CONTINUE
After you redirect the customer to the PayPal subscription consent page, a Continue button appears. Use this option when you want to control the activation of the subscription and do not want PayPal to activate the subscription.


SUBSCRIBE_NOW
After you redirect the customer to the PayPal subscription consent page, a Subscribe Now button appears. Use this option when you want PayPal to activate the subscription.


 
return_url
required
string <uri>   [ 10 .. 4000 ] characters 
The URL where the customer is redirected after the customer approves the payment.


 
cancel_url
required
string <uri>   [ 10 .. 4000 ] characters 
The URL where the customer is redirected after the customer cancels the payment.


 
locale
string <ppaas_common_language_v3>  (language)   [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...
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.


 
object (payment_method) 
The customer and merchant payment preferences. Currently only PAYPAL payment method is supported.


 
{
  • "brand_name": "string",
  • "shipping_preference": "GET_FROM_FILE",
  • "user_action": "CONTINUE",
  • "return_url": "http://example.com",
  • "cancel_url": "http://example.com",
  • "locale": "string",
  • "payment_method": {
    • "payer_selected": "PAYPAL",
    • "payee_preferred": "UNRESTRICTED"
    }
}
application_context
The application context, which customizes the payer experience during the subscription approval process with PayPal.


brand_name
string  [ 1 .. 127 ] characters ^.*$
The label that overrides the business name in the PayPal account on the PayPal site.


 
shipping_preference
string  [ 1 .. 24 ] characters ^[A-Z_]+$
 Default:  "GET_FROM_FILE"
The location from which the shipping address is derived.


 Enum Value Description
GET_FROM_FILE
Get the customer-provided shipping address on the PayPal site.


NO_SHIPPING
Redacts the shipping address from the PayPal site. Recommended for digital goods.


SET_PROVIDED_ADDRESS
Get the merchant-provided address. The customer cannot change this address on the PayPal site. If merchant does not pass an address, customer can choose the address on PayPal pages.


 
return_url
required
string <uri>   [ 10 .. 4000 ] characters 
The URL where the customer is redirected after the customer approves the payment.


 
cancel_url
required
string <uri>   [ 10 .. 4000 ] characters 
The URL where the customer is redirected after the customer cancels the payment.


 
locale
string <ppaas_common_language_v3>  (language)   [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...
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.


 
object (payment_method) 
The customer and merchant payment preferences. Currently only PAYPAL payment method is supported.


 
{
  • "brand_name": "string",
  • "shipping_preference": "GET_FROM_FILE",
  • "return_url": "http://example.com",
  • "cancel_url": "http://example.com",
  • "locale": "string",
  • "payment_method": {
    • "payer_selected": "PAYPAL",
    • "payee_preferred": "UNRESTRICTED"
    }
}
authentication_response
Results of Authentication such as 3D Secure.


liability_shift
string (liability_shift)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Liability shift indicator. The outcome of the issuer's authentication.


 Enum Value Description
YES
Liability has shifted to the card issuer. Available only after order is authorized or captured.


NO
Liability is with the merchant.


POSSIBLE
Liability may shift to the card issuer. Available only before order is authorized or captured.


UNKNOWN
The authentication system is not available.


 
object (three_d_secure_authentication_response) 
Results of 3D Secure Authentication.


 
{
  • "liability_shift": "YES",
  • "three_d_secure": {
    • "authentication_status": "Y",
    • "enrollment_status": "Y"
    }
}
billing_cycle
The billing cycle details.


tenure_type
required
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan.


 Enum Value Description
REGULAR
A regular billing cycle.


TRIAL
A trial billing cycle.


 
sequence
required
integer  [ 1 .. 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
integer  [ 0 .. 999 ] 
 Default:  1
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).


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


 
required
object (frequency) 
The frequency details for this billing cycle.


 
{
  • "tenure_type": "REGULAR",
  • "sequence": 1,
  • "total_cycles": 1,
  • "pricing_scheme": {
    • "version": 999,
    • "pricing_model": "VOLUME",
    • "tiers": [
      • {
        • "starting_quantity": "string",
        • "ending_quantity": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      ],
    • "fixed_price": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "create_time": "string",
    • "update_time": "string"
    },
  • "frequency": {
    • "interval_unit": "DAY",
    • "interval_count": 1
    }
}
billing_cycle_override
The billing cycle details to override at subscription level. The subscription billing cycle definition has to adhere to the plan billing cycle definition.


sequence
required
integer  [ 1 .. 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
integer  [ 0 .. 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).


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


 
{
  • "sequence": 1,
  • "total_cycles": 999,
  • "pricing_scheme": {
    • "version": 999,
    • "pricing_model": "VOLUME",
    • "tiers": [
      • {
        • "starting_quantity": "string",
        • "ending_quantity": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      ],
    • "fixed_price": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "create_time": "string",
    • "update_time": "string"
    }
}
capture_status
The status of a captured payment.


status
string
The status of the captured payment.


 Enum Value Description
COMPLETED
The funds for this captured payment were credited to the payee's PayPal account.


DECLINED
The funds could not be captured.


PARTIALLY_REFUNDED
An amount less than this captured payment's amount was partially refunded to the payer.


PENDING
The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.


REFUNDED
An amount greater than or equal to this captured payment's amount was refunded to the payer.


 
{
  • "status": "COMPLETED"
}
capture_status
The status of a captured payment.


status
string
The status of the captured payment.


 Enum Value Description
COMPLETED
The funds for this captured payment were credited to the payee's PayPal account.


DECLINED
The funds could not be captured.


PARTIALLY_REFUNDED
An amount less than this captured payment's amount was partially refunded to the payer.


PENDING
The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.


REFUNDED
An amount greater than or equal to this captured payment's amount was refunded to the payer.


 
{
  • "status": "COMPLETED"
}
capture_status_details
The details of the captured payment status.


reason
string
The reason why the captured payment status is PENDING or DENIED.


 Enum Value Description
BUYER_COMPLAINT
The payer initiated a dispute for this captured payment with PayPal.


CHARGEBACK
The captured funds were reversed in response to the payer disputing this captured payment with the issuer of the financial instrument used to pay for this captured payment.


ECHECK
The payer paid by an eCheck that has not yet cleared.


INTERNATIONAL_WITHDRAWAL
Visit your online account. In your Account Overview, accept and deny this payment.


OTHER
No additional specific reason can be provided. For more information about this captured payment, visit your account online or contact PayPal.


PENDING_REVIEW
The captured payment is pending manual review.


RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION
The payee has not yet set up appropriate receiving preferences for their account. For more information about how to accept or deny this payment, visit your account online. This reason is typically offered in scenarios such as when the currency of the captured payment is different from the primary holding currency of the payee.


REFUNDED
The captured funds were refunded.


TRANSACTION_APPROVED_AWAITING_FUNDING
The payer must send the funds for this captured payment. This code generally appears for manual EFTs.


UNILATERAL
The payee does not have a PayPal account.


VERIFICATION_REQUIRED
The payee's PayPal account is not verified.


 
{
  • "reason": "BUYER_COMPLAINT"
}
card
The payment card to use to fund a payment. Can be a credit or debit card.


name
string  <= 300 characters 
The card holder's name as it appears on the card.


 
number
required
string  [ 13 .. 19 ] characters 
The primary account number (PAN) for the payment card.


 
security_code
string[0-9]{3,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.


 
expiry
required
string (date_year_month)   = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$
The card expiration year and month, in Internet date format.


 
object (Portable Postal Address (Medium-Grained)) 
The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.


 
{
  • "name": "string",
  • "number": "stringstrings",
  • "security_code": "string",
  • "expiry": "strings",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}
card_brand
The card network or brand. Applies to credit, debit, gift, and payment cards.


string (card_brand)   [ 1 .. 255 ] characters ^[A-Z_]+$
The card network or brand. Applies to credit, debit, gift, and payment cards.


 Enum Value Description
VISA
Visa card.


MASTERCARD
Mastecard card.


DISCOVER
Discover card.


AMEX
American Express card.


SOLO
Solo debit card.


JCB
Japan Credit Bureau card.


STAR
Military Star card.


DELTA
Delta Airlines card.


SWITCH
Switch credit card.


MAESTRO
Maestro credit card.


CB_NATIONALE
Carte Bancaire (CB) credit card.


CONFIGOGA
Configoga credit card.


CONFIDIS
Confidis credit card.


ELECTRON
Visa Electron credit card.


CETELEM
Cetelem credit card.


CHINA_UNION_PAY
China union pay credit card.


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


last_digits
string[0-9]{2,}
The last digits of the payment card.


 
type
string
The payment card type.


 Enum Value Description
CREDIT
A credit card.


DEBIT
A debit card.


PREPAID
A Prepaid card.


UNKNOWN
Card type cannot be determined.


 
object (authentication_response) 
Results of Authentication such as 3D Secure.


 
brand
string (card_brand)   [ 1 .. 255 ] characters ^[A-Z_]+$
The card brand or network. Typically used in the response.


 Enum Value Description
VISA
Visa card.


MASTERCARD
Mastecard card.


DISCOVER
Discover card.


AMEX
American Express card.


SOLO
Solo debit card.


JCB
Japan Credit Bureau card.


STAR
Military Star card.


DELTA
Delta Airlines card.


SWITCH
Switch credit card.


MAESTRO
Maestro credit card.


CB_NATIONALE
Carte Bancaire (CB) credit card.


CONFIGOGA
Configoga credit card.


CONFIDIS
Confidis credit card.


ELECTRON
Visa Electron credit card.


CETELEM
Cetelem credit card.


CHINA_UNION_PAY
China union pay credit card.


 
{
  • "last_digits": "string",
  • "type": "CREDIT",
  • "authentication_result": {
    • "liability_shift": "YES",
    • "three_d_secure": {
      • "authentication_status": "Y",
      • "enrollment_status": "Y"
      }
    },
  • "brand": "VISA"
}
card_response_with_billing_address
The payment card used to fund the payment. Card can be a credit or debit card.


last_digits
string[0-9]{2,}
The last digits of the payment card.


 
type
string
The payment card type.


 Enum Value Description
CREDIT
A credit card.


DEBIT
A debit card.


PREPAID
A Prepaid card.


UNKNOWN
Card type cannot be determined.


 
object (authentication_response) 
Results of Authentication such as 3D Secure.


 
brand
string (card_brand)   [ 1 .. 255 ] characters ^[A-Z_]+$
The card brand or network. Typically used in the response.


 Enum Value Description
VISA
Visa card.


MASTERCARD
Mastecard card.


DISCOVER
Discover card.


AMEX
American Express card.


SOLO
Solo debit card.


JCB
Japan Credit Bureau card.


STAR
Military Star card.


DELTA
Delta Airlines card.


SWITCH
Switch credit card.


MAESTRO
Maestro credit card.


CB_NATIONALE
Carte Bancaire (CB) credit card.


CONFIGOGA
Configoga credit card.


CONFIDIS
Confidis credit card.


ELECTRON
Visa Electron credit card.


CETELEM
Cetelem credit card.


CHINA_UNION_PAY
China union pay credit card.


 
name
string  [ 2 .. 300 ] characters 
The card holder's name as it appears on the card.


 
object (Portable Postal Address (Medium-Grained)) 
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


 
expiry
string (date_year_month)   = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$
The card expiration year and month, in Internet date format.


 
currency_code
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
Currency code of the given instrument


 
{
  • "last_digits": "string",
  • "type": "CREDIT",
  • "authentication_result": {
    • "liability_shift": "YES",
    • "three_d_secure": {
      • "authentication_status": "Y",
      • "enrollment_status": "Y"
      }
    },
  • "brand": "VISA",
  • "name": "string",
  • "billing_address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    },
  • "expiry": "strings",
  • "currency_code": "str"
}
country_code
The two-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.


string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-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.


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


string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
"str"
cycle_execution
The regular and trial execution details for a billing cycle.


tenure_type
required
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The type of the billing cycle.


 Enum Value Description
REGULAR
A regular billing cycle.


TRIAL
A trial billing cycle.


 
sequence
required
integer  [ 0 .. 99 ] 
The order in which to run this cycle among other billing cycles.


 
cycles_completed
required
integer  [ 0 .. 9999 ] 
The number of billing cycles that have completed.


 
cycles_remaining
integer  [ 0 .. 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
integer  [ 1 .. 99 ] 
The active pricing scheme version for the billing cycle.


 
total_cycles
integer  [ 0 .. 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).


 
{
  • "tenure_type": "REGULAR",
  • "sequence": 99,
  • "cycles_completed": 9999,
  • "cycles_remaining": 9999,
  • "current_pricing_scheme_version": 1,
  • "total_cycles": 999
}
date_no_time
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


string <ppaas_date_notime_v2>  (date_no_time)   = 10 characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The stand-alone date, in Internet date and time format. To represent special legal values, such as a date of birth, you should use dates with no associated time or time-zone data. Whenever possible, use the standard date_time type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.


 
"stringstri"
date_time
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
"stringstringstringst"
date_year_month
The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.


string (date_year_month)   = 7 characters ^[0-9]{4}-(0[1-9]|1[0-2])$
The year and month, in ISO-8601 YYYY-MM date format. See Internet date and time format.


 
"strings"
email
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


string <merchant_common_email_address_v2>  (email)   <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


 
"string"
email_address
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


string <ppaas_common_email_address_v2>  (email_address)   [ 3 .. 254 ] characters ^.+@[^"\-].+$
The internationalized email address.
Note: Up to 64 characters are allowed before and 255 characters are allowed after the @ sign. However, the generally accepted maximum length for an email address is 254 characters. The pattern verifies that an unquoted @ sign exists.


 
"string"
enrolled
Status of Authentication eligibility.


string (enrolled)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Status of Authentication eligibility.


 Enum Value Description
Y
Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl.


N
No. The bank is not participating in 3-D Secure protocol.


U
Unavailable. The DS or ACS is not available for authentication at the time of the request.


B
Bypass. The merchant authentication rule is triggered to bypass authentication.


 
"Y"
Error
The error details.


name
required
string
The human-readable, unique name of the error.


 
message
required
string
The message that describes the error.


 
debug_id
required
string
The PayPal internal ID. Used for correlation purposes.


 
information_link
string
The information link, or URI, that shows detailed information about this error for the developer.


 
Array of objects (Error Details) 
An array of additional details about the error.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "name": "string",
  • "message": "string",
  • "debug_id": "string",
  • "information_link": "string",
  • "details": [
    • {
      • "field": "string",
      • "value": "string",
      • "location": "body",
      • "issue": "string",
      • "description": "string"
      }
    ],
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
Error Details
The error details. Required for client-side 4XX errors.


field
string
The field that caused the error. If this field is in the body, set this value to the field's JSON pointer value. Required for client-side errors.


 
value
string
The value of the field that caused the error.


 
location
string
 Default:  "body"
The location of the field that caused the error. Value is body, path, or query.


 
issue
required
string
The unique, fine-grained application-level error code.


 
description
string
The human-readable description for an issue. The description can change over the lifetime of an API, so clients must not depend on this value.


 
{
  • "field": "string",
  • "value": "string",
  • "location": "body",
  • "issue": "string",
  • "description": "string"
}
failed_payment_details
The details for the failed payment of the subscription.


reason_code
string  [ 1 .. 120 ] characters ^[A-Z_]+$
The reason code for the payment failure.


 Enum Value Description
PAYMENT_DENIED
PayPal declined the payment due to one or more customer issues.


INTERNAL_SERVER_ERROR
An internal server error has occurred.


PAYEE_ACCOUNT_RESTRICTED
The payee account is not in good standing and cannot receive payments.


PAYER_ACCOUNT_RESTRICTED
The payer account is not in good standing and cannot make payments.


PAYER_CANNOT_PAY
Payer cannot pay for this transaction.


SENDING_LIMIT_EXCEEDED
The transaction exceeds the payer's sending limit.


TRANSACTION_RECEIVING_LIMIT_EXCEEDED
The transaction exceeds the receiver's receiving limit.


CURRENCY_MISMATCH
The transaction is declined due to a currency mismatch.


 
required
object (Money) 
The failed payment amount.


 
time
required
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when the failed payment was made, in Internet date and time format.


 
next_payment_retry_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The time when the retry attempt for the failed payment occurs, in Internet date and time format.


 
{
  • "reason_code": "PAYMENT_DENIED",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "time": "string",
  • "next_payment_retry_time": "string"
}
frequency
The frequency of the billing cycle.


interval_unit
required
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The interval at which the subscription is charged or billed.


 Enum Value Description
DAY
A daily billing cycle.


WEEK
A weekly billing cycle.


MONTH
A monthly billing cycle.


YEAR
A yearly billing cycle.


 
interval_count
integer  [ 1 .. 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 unitMaximum interval count
DAY365
WEEK52
MONTH12
YEAR1


 
{
  • "interval_unit": "DAY",
  • "interval_count": 1
}
language
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.


string <ppaas_common_language_v3>  (language)   [ 2 .. 10 ] characters ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))...
The language tag for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the ISO 639-2 language code, the optional ISO-15924 script tag, and the ISO-3166 alpha-2 country code.


 
"string"
last_payment_details
The details for the last payment.


status
string
The status of the captured payment.


 Enum Value Description
COMPLETED
The funds for this captured payment were credited to the payee's PayPal account.


DECLINED
The funds could not be captured.


PARTIALLY_REFUNDED
An amount less than this captured payment's amount was partially refunded to the payer.


PENDING
The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.


REFUNDED
An amount greater than or equal to this captured payment's amount was refunded to the payer.


 
required
object (Money) 
The last payment amount.


 
time
required
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when the last payment was made, in Internet date and time format.


 
{
  • "status": "COMPLETED",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "time": "string"
}
liability_shift
Liability shift indicator. The outcome of the issuer's authentication.


string (liability_shift)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Liability shift indicator. The outcome of the issuer's authentication.


 Enum Value Description
YES
Liability has shifted to the card issuer. Available only after order is authorized or captured.


NO
Liability is with the merchant.


POSSIBLE
Liability may shift to the card issuer. Available only before order is authorized or captured.


UNKNOWN
The authentication system is not available.


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


currency_code
required
string <ppaas_common_currency_code_v2>  (currency_code)   = 3 characters 
The three-character ISO-4217 currency code that identifies the currency.


 
value
required
string  <= 32 characters ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
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.


 
{
  • "currency_code": "str",
  • "value": "string"
}
Name
The name of the party.


given_name
string  <= 140 characters 
When the party is a person, the party's given, or first, name.


 
surname
string  <= 140 characters 
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.


 
{
  • "given_name": "string",
  • "surname": "string"
}
Name
The name of the party.


full_name
string  <= 300 characters 
When the party is a person, the party's full name.


 
{
  • "full_name": "string"
}
Name
The name of the party.


prefix
string  <= 140 characters 
The prefix, or title, to the party's name.


 
given_name
string  <= 140 characters 
When the party is a person, the party's given, or first, name.


 
surname
string  <= 140 characters 
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.


 
middle_name
string  <= 140 characters 
When the party is a person, the party's middle name. Use also to store multiple middle names including the patronymic, or father's, middle name.


 
suffix
string  <= 140 characters 
The suffix for the party's name.


 
alternate_full_name
string  <= 300 characters 
DEPRECATED. The party's alternate name. Can be a business name, nickname, or any other name that cannot be split into first, last name. Required when the party is a business.


 
full_name
string  <= 300 characters 
When the party is a person, the party's full name.


 
{
  • "prefix": "string",
  • "given_name": "string",
  • "surname": "string",
  • "middle_name": "string",
  • "suffix": "string",
  • "alternate_full_name": "string",
  • "full_name": "string"
}
Name
The name of the party.


given_name
string  <= 140 characters 
When the party is a person, the party's given, or first, name.


 
surname
string  <= 140 characters 
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.


 
{
  • "given_name": "string",
  • "surname": "string"
}
pares_status
Transactions status result identifier. The outcome of the issuer's authentication.


string (pares_status)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Transactions status result identifier. The outcome of the issuer's authentication.


 Enum Value Description
Y
Successful authentication.


N
Failed authentication / account not verified / transaction denied.


U
Unable to complete authentication.


A
Successful attempts transaction.


C
Challenge required for authentication.


R
Authentication rejected (merchant must not submit for authorization).


D
Challenge required; decoupled authentication confirmed.


I
Informational only; 3DS requestor challenge preference acknowledged.


 
"Y"
Patch
The JSON patch object to apply partial updates to resources.


op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
object (Patch Value) 
The value to apply. The remove operation does not require a value.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
{
  • "op": "add",
  • "path": "string",
  • "value": { },
  • "from": "string"
}
Patch Request
An array of JSON patch objects to apply partial updates to resources.


 Array 
op
required
string
The operation.


 Enum Value Description
add
Depending on the target location reference, completes one of these functions:
  • The target location is an array index. Inserts a new value into the array at the specified index.
  • The target location is an object parameter that does not already exist. Adds a new parameter to the object.
  • The target location is an object parameter that does exist. Replaces that parameter's value.
The value parameter defines the value to add. For more information, see 4.1. add.


remove
Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see 4.2. remove.


replace
Replaces the value at the target location with a new value. The operation object must contain a value parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see 4.3. replace.


move
Removes the value at a specified location and adds it to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to move the value. For the operation to succeed, the from location must exist. For more information, see 4.4. move.


copy
Copies the value at a specified location to the target location. The operation object must contain a from parameter, which is a string that contains a JSON pointer value that references the location in the target document from which to copy the value. For the operation to succeed, the from location must exist. For more information, see 4.5. copy.


test
Tests that a value at the target location is equal to a specified value. The operation object must contain a value parameter that defines the value to compare to the target location's value. For the operation to succeed, the target location must be equal to the value value. For test, equal indicates that the value at the target location and the value that value defines are of the same JSON type. The data type of the value determines how equality is defined:
TypeConsidered equal if both values
stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
numbersAre numerically equal.
arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
For more information, see 4.6. test.


 
path
string
The JSON Pointer to the target document location at which to complete the operation.


 
value
object (Patch Value) 
The value to apply. The remove operation does not require a value.


 
from
string
The JSON Pointer to the target document location from which to move the value. Required for the move operation.


 
[
  • {
    • "op": "add",
    • "path": "string",
    • "value": { },
    • "from": "string"
    }
]
payee_payment_method_preference
The merchant-preferred payment methods.


string (payee_payment_method_preference)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
 Default:  "UNRESTRICTED"
The merchant-preferred payment methods.


 Enum Value Description
UNRESTRICTED
Accepts any type of payment from the customer.


IMMEDIATE_PAYMENT_REQUIRED
Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the pending status.


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


email_address
string <merchant_common_email_address_v2>  (email)   <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...
The email address of the payer.


 
payer_id
string <ppaas_payer_id_v3>  (PayPal Account Identifier)   = 13 characters ^[2-9A-HJ-NP-Z]{13}$
The PayPal-assigned ID for the payer.


 
object (Name) 
The name of the payer. Supports only the given_name and surname properties.


 
object (phone_with_type) 
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.


 
{
  • "email_address": "string",
  • "payer_id": "stringstrings",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    }
}
payer
The customer who approves and pays for the order. The customer is also known as the payer.


email_address
string <merchant_common_email_address_v2>  (email)   <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...
The email address of the payer.


 
payer_id
string <ppaas_payer_id_v3>  (PayPal Account Identifier)   = 13 characters ^[2-9A-HJ-NP-Z]{13}$
The PayPal-assigned ID for the payer.


 
object (Name) 
The name of the payer. Supports only the given_name and surname properties.


 
object (phone_with_type) 
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.


 
{
  • "email_address": "string",
  • "payer_id": "stringstrings",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    }
}
payer_base
The customer who approves and pays for the order. The customer is also known as the payer.


email_address
string <merchant_common_email_address_v2>  (email)   <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...
The email address of the payer.


 
payer_id
string <ppaas_payer_id_v3>  (PayPal Account Identifier)   = 13 characters ^[2-9A-HJ-NP-Z]{13}$
The PayPal-assigned ID for the payer.


 
{
  • "email_address": "string",
  • "payer_id": "stringstrings"
}
payment_method
The customer and merchant payment preferences.


payer_selected
string  non-empty ^[0-9A-Z_]+$
 Default:  "PAYPAL"
The customer-selected payment method on the merchant site.


 
payee_preferred
string (payee_payment_method_preference)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
 Default:  "UNRESTRICTED"
The merchant-preferred payment methods.


 Enum Value Description
UNRESTRICTED
Accepts any type of payment from the customer.


IMMEDIATE_PAYMENT_REQUIRED
Accepts only immediate payment from the customer. For example, credit card, PayPal balance, or instant ACH. Ensures that at the time of capture, the payment does not have the pending status.


 
{
  • "payer_selected": "PAYPAL",
  • "payee_preferred": "UNRESTRICTED"
}
payment_preferences
The payment preferences for a subscription.


auto_bill_outstanding
boolean
 Default:  true
Indicates whether to automatically bill the outstanding amount in the next billing cycle.


 
setup_fee_failure_action
string  [ 1 .. 24 ] characters ^[A-Z_]+$
 Default:  "CANCEL"
The action to take on the subscription if the initial payment for the setup fails.


 Enum Value Description
CONTINUE
Continues the subscription if the initial payment for the setup fails.


CANCEL
Cancels the subscription if the initial payment for the setup fails.


 
payment_failure_threshold
integer  [ 0 .. 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.


 
object (Money) 
The initial set-up fee for the service.


 
{
  • "auto_bill_outstanding": true,
  • "setup_fee_failure_action": "CONTINUE",
  • "payment_failure_threshold": 0,
  • "setup_fee": {
    • "currency_code": "str",
    • "value": "string"
    }
}
payment_preferences_override
The payment preferences to override at subscription level.


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


 
setup_fee_failure_action
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The action to take on the subscription if the initial payment for the setup fails.


 Enum Value Description
CONTINUE
Continues the subscription if the initial payment for the setup fails.


CANCEL
Cancels the subscription if the initial payment for the setup fails.


 
payment_failure_threshold
integer  [ 0 .. 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.


 
object (Money) 
The initial set-up fee for the service.


 
{
  • "auto_bill_outstanding": true,
  • "setup_fee_failure_action": "CONTINUE",
  • "payment_failure_threshold": 999,
  • "setup_fee": {
    • "currency_code": "str",
    • "value": "string"
    }
}
payment_source
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.


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


 
{
  • "card": {
    • "name": "string",
    • "number": "stringstrings",
    • "security_code": "string",
    • "expiry": "strings",
    • "billing_address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    }
}
payment_source_response
The payment source used to fund the payment.


object (card_response_with_billing_address) 
The payment card used to fund the payment. Card can be a credit or debit card.


 
{
  • "card": {
    • "last_digits": "string",
    • "type": "CREDIT",
    • "authentication_result": {
      • "liability_shift": "YES",
      • "three_d_secure": {
        • "authentication_status": "Y",
        • "enrollment_status": "Y"
        }
      },
    • "brand": "VISA",
    • "name": "string",
    • "billing_address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      },
    • "expiry": "strings",
    • "currency_code": "str"
    }
}
PayPal Account Identifier
The account identifier for a PayPal account.


string <ppaas_payer_id_v3>  (PayPal Account Identifier)   = 13 characters ^[2-9A-HJ-NP-Z]{13}$
The account identifier for a PayPal account.


 
"stringstrings"
percentage
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.


string <ppaas_common_percentage_v2>  (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as 19.99.


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


national_number
required
string  [ 1 .. 14 ] characters ^[0-9]{1,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).


 
{
  • "national_number": "string"
}
Phone Type
The phone type.


string (Phone Type) 
The phone type.


 Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"  
"FAX"
phone_with_type
The phone information.


phone_type
string (Phone Type) 
The phone type.


 Enum: "FAX" "HOME" "MOBILE" "OTHER" "PAGER"  
required
object (Phone) 
The phone number, in its canonical international E.164 numbering plan format. Supports only the national_number property.


 
{
  • "phone_type": "FAX",
  • "phone_number": {
    • "national_number": "string"
    }
}
plan
The plan details.


id
string  = 26 characters ^P-[A-Z0-9]*$
The unique PayPal-generated ID for the plan.


 
product_id
string  = 22 characters ^PROD-[A-Z0-9]*$
The ID for the product.


 
name
string  [ 1 .. 127 ] characters ^.*$
The plan name.


 
status
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The plan status.


 Enum Value Description
CREATED
The plan was created. You cannot create subscriptions for a plan in this state.


INACTIVE
The plan is inactive.


ACTIVE
The plan is active. You can only create subscriptions for a plan in this state.


 
description
string  [ 1 .. 127 ] characters ^.*$
The detailed description of the plan.


 
Array of objects (billing_cycle)   [ 1 .. 12 ] items 
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.


 
quantity_supported
boolean
 Default:  false
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.


 
Array of objects (Link Description)   [ 1 .. 10 ] items 
An array of request-related HATEOAS links.


 
object (payment_preferences) 
The payment preferences for a subscription.


 
object (taxes) 
The tax details.


 
create_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when the plan was created, in Internet date and time format.


 
update_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when the plan was last updated, in Internet date and time format.


 
{
  • "id": "stringstringstringstringst",
  • "product_id": "stringstringstringstri",
  • "name": "string",
  • "status": "CREATED",
  • "description": "string",
  • "billing_cycles": [
    • {
      • "tenure_type": "REGULAR",
      • "sequence": 1,
      • "total_cycles": 1,
      • "pricing_scheme": {
        • "version": 999,
        • "pricing_model": "VOLUME",
        • "tiers": [
          • {
            • "starting_quantity": "string",
            • "ending_quantity": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          ],
        • "fixed_price": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "create_time": "string",
        • "update_time": "string"
        },
      • "frequency": {
        • "interval_unit": "DAY",
        • "interval_count": 1
        }
      }
    ],
  • "quantity_supported": false,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 0,
    • "setup_fee": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "taxes": {
    • "inclusive": true,
    • "percentage": "string"
    },
  • "create_time": "string",
  • "update_time": "string"
}
plan
The plan details.


product_id
string  = 22 characters ^PROD-[A-Z0-9]*$
The ID for the product.


 
name
string  [ 1 .. 127 ] characters ^.*$
The plan name.


 
description
string  [ 1 .. 127 ] characters ^.*$
The detailed description of the plan.


 
Array of objects (billing_cycle)   [ 1 .. 12 ] items 
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.


 
quantity_supported
boolean
 Default:  false
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.


 
object (payment_preferences) 
The payment preferences for a subscription.


 
object (taxes) 
The tax details.


 
{
  • "product_id": "stringstringstringstri",
  • "name": "string",
  • "description": "string",
  • "billing_cycles": [
    • {
      • "tenure_type": "REGULAR",
      • "sequence": 1,
      • "total_cycles": 1,
      • "pricing_scheme": {
        • "version": 999,
        • "pricing_model": "VOLUME",
        • "tiers": [
          • {
            • "starting_quantity": "string",
            • "ending_quantity": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          ],
        • "fixed_price": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "create_time": "string",
        • "update_time": "string"
        },
      • "frequency": {
        • "interval_unit": "DAY",
        • "interval_count": 1
        }
      }
    ],
  • "quantity_supported": false,
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 0,
    • "setup_fee": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "taxes": {
    • "inclusive": true,
    • "percentage": "string"
    }
}
plan_collection
The list of plans with details.


Array of objects (plan)   [ 0 .. 32767 ] items 
An array of plans.


 
total_items
integer  [ 0 .. 500000000 ] 
The total number of items.


 
total_pages
integer  [ 0 .. 100000000 ] 
The total number of pages.


 
Array of objects (Link Description)   [ 1 .. 10 ] items 
An array of request-related HATEOAS links.


 
{
  • "plans": [
    • {
      • "id": "stringstringstringstringst",
      • "product_id": "stringstringstringstri",
      • "name": "string",
      • "status": "CREATED",
      • "description": "string",
      • "billing_cycles": [
        • {
          • "tenure_type": "REGULAR",
          • "sequence": 1,
          • "total_cycles": 1,
          • "pricing_scheme": {
            • "version": 999,
            • "pricing_model": "VOLUME",
            • "tiers": [
              • {
                • "starting_quantity": null,
                • "ending_quantity": null,
                • "amount": null
                }
              ],
            • "fixed_price": {
              • "currency_code": "str",
              • "value": "string"
              },
            • "create_time": "string",
            • "update_time": "string"
            },
          • "frequency": {
            • "interval_unit": "DAY",
            • "interval_count": 1
            }
          }
        ],
      • "quantity_supported": false,
      • "links": [
        • {
          • "href": "string",
          • "rel": "string",
          • "method": "GET"
          }
        ],
      • "payment_preferences": {
        • "auto_bill_outstanding": true,
        • "setup_fee_failure_action": "CONTINUE",
        • "payment_failure_threshold": 0,
        • "setup_fee": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "taxes": {
        • "inclusive": true,
        • "percentage": "string"
        },
      • "create_time": "string",
      • "update_time": "string"
      }
    ],
  • "total_items": 500000000,
  • "total_pages": 100000000,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
plan_override
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.


Array of objects (billing_cycle_override)   [ 1 .. 12 ] items 
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.


 
object (payment_preferences_override) 
The payment preferences to override at subscription level.


 
object (taxes_override) 
The tax details.


 
{
  • "billing_cycles": [
    • {
      • "sequence": 1,
      • "total_cycles": 999,
      • "pricing_scheme": {
        • "version": 999,
        • "pricing_model": "VOLUME",
        • "tiers": [
          • {
            • "starting_quantity": "string",
            • "ending_quantity": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          ],
        • "fixed_price": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "create_time": "string",
        • "update_time": "string"
        }
      }
    ],
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 999,
    • "setup_fee": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "taxes": {
    • "inclusive": true,
    • "percentage": "string"
    }
}
plan_request
The create plan request details.


product_id
required
string  = 22 characters ^PROD-[A-Z0-9]*$
The ID of the product created through Catalog Products API.


 
name
required
string  [ 1 .. 127 ] characters ^.*$
The plan name.


 
status
string  [ 1 .. 24 ] characters ^[A-Z_]+$
 Default:  "ACTIVE"
The initial state of the plan. Allowed input values are CREATED and ACTIVE.


 Enum Value Description
CREATED
The plan was created. You cannot create subscriptions for a plan in this state.


INACTIVE
The plan is inactive.


ACTIVE
The plan is active. You can only create subscriptions for a plan in this state.


 
description
string  [ 1 .. 127 ] characters ^.*$
The detailed description of the plan.


 
required
Array of objects (billing_cycle)   [ 1 .. 12 ] items 
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.


 
quantity_supported
boolean
 Default:  false
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.


 
required
object (payment_preferences) 
The payment preferences for a subscription.


 
object (taxes) 
The tax details.


 
{
  • "product_id": "stringstringstringstri",
  • "name": "string",
  • "status": "CREATED",
  • "description": "string",
  • "billing_cycles": [
    • {
      • "tenure_type": "REGULAR",
      • "sequence": 1,
      • "total_cycles": 1,
      • "pricing_scheme": {
        • "version": 999,
        • "pricing_model": "VOLUME",
        • "tiers": [
          • {
            • "starting_quantity": "string",
            • "ending_quantity": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          ],
        • "fixed_price": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "create_time": "string",
        • "update_time": "string"
        },
      • "frequency": {
        • "interval_unit": "DAY",
        • "interval_count": 1
        }
      }
    ],
  • "quantity_supported": false,
  • "payment_preferences": {
    • "auto_bill_outstanding": true,
    • "setup_fee_failure_action": "CONTINUE",
    • "payment_failure_threshold": 0,
    • "setup_fee": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "taxes": {
    • "inclusive": true,
    • "percentage": "string"
    }
}
Portable Postal Address (Medium-Grained)
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


address_line_1
string  <= 300 characters 
The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.


 
address_line_2
string  <= 300 characters 
The second line of the address. For example, suite or apartment number.


 
admin_area_2
string  <= 120 characters 
A city, town, or village. Smaller than admin_area_level_1.


 
admin_area_1
string  <= 300 characters 
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format 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
string  <= 60 characters 
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_code
required
string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-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.


 
{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}
Portable Postal Address (Medium-Grained)
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


address_line_1
string  <= 300 characters 
The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.


 
address_line_2
string  <= 300 characters 
The second line of the address. For example, suite or apartment number.


 
admin_area_2
string  <= 120 characters 
A city, town, or village. Smaller than admin_area_level_1.


 
admin_area_1
string  <= 300 characters 
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format 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
string  <= 60 characters 
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_code
required
string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-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.


 
{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}
Portable Postal Address (Medium-Grained)
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


address_line_1
string  <= 300 characters 
The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.


 
address_line_2
string  <= 300 characters 
The second line of the address. For example, suite or apartment number.


 
admin_area_2
string  <= 120 characters 
A city, town, or village. Smaller than admin_area_level_1.


 
admin_area_1
string  <= 300 characters 
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format 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
string  <= 60 characters 
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_code
required
string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-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.


 
{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}
Portable Postal Address (Medium-Grained)
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


address_line_1
string  <= 300 characters 
The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.


 
address_line_2
string  <= 300 characters 
The second line of the address. For example, suite or apartment number.


 
admin_area_2
string  <= 120 characters 
A city, town, or village. Smaller than admin_area_level_1.


 
admin_area_1
string  <= 300 characters 
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format 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
string  <= 60 characters 
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_code
required
string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-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.


 
{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}
Portable Postal Address (Medium-Grained)
The portable international postal address. Maps to AddressValidationMetadata and HTML 5.1 Autofilling form controls: the autocomplete attribute.


address_line_1
string  <= 300 characters 
The first line of the address. For example, number or street. For example, 173 Drury Lane. Required for data entry and compliance and risk checks. Must contain the full address.


 
address_line_2
string  <= 300 characters 
The second line of the address. For example, suite or apartment number.


 
admin_area_2
string  <= 120 characters 
A city, town, or village. Smaller than admin_area_level_1.


 
admin_area_1
string  <= 300 characters 
The highest level sub-division in a country, which is usually a province, state, or ISO-3166-2 subdivision. Format 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
string  <= 60 characters 
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_code
required
string <ppaas_common_country_code_v2>  (country_code)   = 2 characters ^([A-Z]{2}|C2)$
The two-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.


 
{
  • "address_line_1": "string",
  • "address_line_2": "string",
  • "admin_area_2": "string",
  • "admin_area_1": "string",
  • "postal_code": "string",
  • "country_code": "st"
}
pricing_scheme
The pricing scheme details.


version
integer  [ 0 .. 999 ] 
The version of the pricing scheme.


 
pricing_model
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The pricing model for tiered plan. The tiers parameter is required.


 Enum Value Description
VOLUME
A volume pricing model.


TIERED
A tiered pricing model.


 
Array of objects (pricing_tier)   [ 1 .. 32 ] items 
An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified.


 
object (Money) 
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.


 
create_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when this pricing scheme was created, in Internet date and time format.


 
update_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when this pricing scheme was last updated, in Internet date and time format.


 
{
  • "version": 999,
  • "pricing_model": "VOLUME",
  • "tiers": [
    • {
      • "starting_quantity": "string",
      • "ending_quantity": "string",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        }
      }
    ],
  • "fixed_price": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "create_time": "string",
  • "update_time": "string"
}
pricing_tier
The pricing tier details.


starting_quantity
required
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The starting quantity for the tier.


 
ending_quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The ending quantity for the tier. Optional for the last tier.


 
required
object (Money) 
The pricing amount for the tier.


 
{
  • "starting_quantity": "string",
  • "ending_quantity": "string",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
shipping_detail
The shipping details.


type
string  [ 1 .. 255 ] characters ^[0-9A-Z_]+$
The method by which the payer wants to get their items from the payee e.g shipping, in-person pickup. Either type or options but not both may be present.


 Enum Value Description
SHIPPING
The payer intends to receive the items at a specified address.


PICKUP_IN_PERSON
The payer intends to pick up the items from the payee in person.


 
object (Name) 
The name of the person to whom to ship the items. Supports only the full_name property.


 
object (Portable Postal Address (Medium-Grained)) 
The address of the person to whom to ship the items. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.


 
{
  • "type": "SHIPPING",
  • "name": {
    • "full_name": "string"
    },
  • "address": {
    • "address_line_1": "string",
    • "address_line_2": "string",
    • "admin_area_2": "string",
    • "admin_area_1": "string",
    • "postal_code": "string",
    • "country_code": "st"
    }
}
subscriber
The subscriber response information.


email_address
string <merchant_common_email_address_v2>  (email)   <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...
The email address of the payer.


 
payer_id
string <ppaas_payer_id_v3>  (PayPal Account Identifier)   = 13 characters ^[2-9A-HJ-NP-Z]{13}$
The PayPal-assigned ID for the payer.


 
object (Name) 
The name of the payer. Supports only the given_name and surname properties.


 
object (phone_with_type) 
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.


 
object (shipping_detail) 
The shipping details.


 
object (payment_source_response) 
The payment source used to fund the payment.


 
{
  • "email_address": "string",
  • "payer_id": "stringstrings",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    },
  • "shipping_address": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "payment_source": {
    • "card": {
      • "last_digits": "string",
      • "type": "CREDIT",
      • "authentication_result": {
        • "liability_shift": "YES",
        • "three_d_secure": {
          • "authentication_status": "Y",
          • "enrollment_status": "Y"
          }
        },
      • "brand": "VISA",
      • "name": "string",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        },
      • "expiry": "strings",
      • "currency_code": "str"
      }
    }
}
subscriber_request
The subscriber request information .


email_address
string <merchant_common_email_address_v2>  (email)   <= 254 characters (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-...
The email address of the payer.


 
payer_id
string <ppaas_payer_id_v3>  (PayPal Account Identifier)   = 13 characters ^[2-9A-HJ-NP-Z]{13}$
The PayPal-assigned ID for the payer.


 
object (Name) 
The name of the payer. Supports only the given_name and surname properties.


 
object (phone_with_type) 
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.


 
object (shipping_detail) 
The shipping details.


 
object (payment_source) 
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.


 
{
  • "email_address": "string",
  • "payer_id": "stringstrings",
  • "name": {
    • "given_name": "string",
    • "surname": "string"
    },
  • "phone": {
    • "phone_type": "FAX",
    • "phone_number": {
      • "national_number": "string"
      }
    },
  • "shipping_address": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "payment_source": {
    • "card": {
      • "name": "string",
      • "number": "stringstrings",
      • "security_code": "string",
      • "expiry": "strings",
      • "billing_address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        }
      }
    }
}
subscription
The subscription details.


status
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The status of the subscription.


 Enum Value Description
APPROVAL_PENDING
The subscription is created but not yet approved by the buyer.


APPROVED
The buyer has approved the subscription.


ACTIVE
The subscription is active.


SUSPENDED
The subscription is suspended.


CANCELLED
The subscription is cancelled.


EXPIRED
The subscription is expired.


 
status_change_note
string  [ 1 .. 128 ] characters ^.*$
The reason or notes for the status of the subscription.


 
status_update_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
id
string  [ 3 .. 50 ] characters 
The PayPal-generated ID for the subscription.


 
plan_id
string  [ 3 .. 50 ] characters 
The ID of the plan.


 
quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The quantity of the product in the subscription.


 
custom_id
string  [ 1 .. 127 ] characters ^[\x20-\x7E]+
The custom id for the subscription. Can be invoice id.


 
plan_overridden
boolean
Indicates whether the subscription has overridden any plan attributes.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
start_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


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


 
object <payer_v1>  (subscriber) 
The subscriber response information.


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


 
create_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
update_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
object (plan) 
Inline plan details.


 
{
  • "status": "APPROVAL_PENDING",
  • "status_change_note": "string",
  • "status_update_time": "string",
  • "id": "string",
  • "plan_id": "string",
  • "quantity": "string",
  • "custom_id": "string",
  • "plan_overridden": true,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ],
  • "start_time": "string",
  • "shipping_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "subscriber": {
    • "email_address": "string",
    • "payer_id": "stringstrings",
    • "name": {
      • "given_name": "string",
      • "surname": "string"
      },
    • "phone": {
      • "phone_type": "FAX",
      • "phone_number": {
        • "national_number": "string"
        }
      },
    • "shipping_address": {
      • "type": "SHIPPING",
      • "name": {
        • "full_name": "string"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        }
      },
    • "payment_source": {
      • "card": {
        • "last_digits": "string",
        • "type": "CREDIT",
        • "authentication_result": {
          • "liability_shift": "YES",
          • "three_d_secure": {
            • "authentication_status": "Y",
            • "enrollment_status": "Y"
            }
          },
        • "brand": "VISA",
        • "name": "string",
        • "billing_address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st"
          },
        • "expiry": "strings",
        • "currency_code": "str"
        }
      }
    },
  • "billing_info": {
    • "cycle_executions": [
      • {
        • "tenure_type": "REGULAR",
        • "sequence": 99,
        • "cycles_completed": 9999,
        • "cycles_remaining": 9999,
        • "current_pricing_scheme_version": 1,
        • "total_cycles": 999
        }
      ],
    • "failed_payments_count": 999,
    • "outstanding_balance": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "last_payment": {
      • "status": "COMPLETED",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "time": "string"
      },
    • "next_billing_time": "string",
    • "final_payment_time": "string",
    • "last_failed_payment": {
      • "reason_code": "PAYMENT_DENIED",
      • "amount": {
        • "currency_code": "str",
        • "value": "string"
        },
      • "time": "string",
      • "next_payment_retry_time": "string"
      }
    },
  • "create_time": "string",
  • "update_time": "string",
  • "plan": {
    • "product_id": "stringstringstringstri",
    • "name": "string",
    • "description": "string",
    • "billing_cycles": [
      • {
        • "tenure_type": "REGULAR",
        • "sequence": 1,
        • "total_cycles": 1,
        • "pricing_scheme": {
          • "version": 999,
          • "pricing_model": "VOLUME",
          • "tiers": [
            • {
              • "starting_quantity": "string",
              • "ending_quantity": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              }
            ],
          • "fixed_price": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "create_time": "string",
          • "update_time": "string"
          },
        • "frequency": {
          • "interval_unit": "DAY",
          • "interval_count": 1
          }
        }
      ],
    • "quantity_supported": false,
    • "payment_preferences": {
      • "auto_bill_outstanding": true,
      • "setup_fee_failure_action": "CONTINUE",
      • "payment_failure_threshold": 0,
      • "setup_fee": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "taxes": {
      • "inclusive": true,
      • "percentage": "string"
      }
    }
}
subscription_activate_request
The activate subscription request details.


reason
string  [ 1 .. 128 ] characters ^.*$
The reason for activation of a subscription. Required to reactivate the subscription.


 
{
  • "reason": "string"
}
subscription_billing_info
The billing details for the subscription. If the subscription was or is active, these fields are populated.


Array of objects (cycle_execution)   [ 0 .. 3 ] items 
The trial and regular billing executions.


 
failed_payments_count
required
integer  [ 0 .. 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.


 
required
object (Money) 
The total pending bill amount, to be paid by the subscriber.


 
object (last_payment_details) 
The details for the last payment of the subscription.


 
next_billing_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The next date and time for billing this subscription, in Internet date and time format.


 
final_payment_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when the final billing cycle occurs, in Internet date and time format.


 
object (failed_payment_details) 
The details for the last failed payment of the subscription.


 
{
  • "cycle_executions": [
    • {
      • "tenure_type": "REGULAR",
      • "sequence": 99,
      • "cycles_completed": 9999,
      • "cycles_remaining": 9999,
      • "current_pricing_scheme_version": 1,
      • "total_cycles": 999
      }
    ],
  • "failed_payments_count": 999,
  • "outstanding_balance": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "last_payment": {
    • "status": "COMPLETED",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "time": "string"
    },
  • "next_billing_time": "string",
  • "final_payment_time": "string",
  • "last_failed_payment": {
    • "reason_code": "PAYMENT_DENIED",
    • "amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "time": "string",
    • "next_payment_retry_time": "string"
    }
}
subscription_cancel_request
The cancel subscription request details.


reason
required
string  [ 1 .. 128 ] characters ^.*$
The reason for the cancellation of a subscription.


 
{
  • "reason": "string"
}
subscription_capture_request
The charge amount from the subscriber.


note
required
string  [ 1 .. 128 ] characters ^.*$
The reason or note for the subscription charge.


 
capture_type
required
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The type of capture.


 Value Description
OUTSTANDING_BALANCE
The outstanding balance that the subscriber must clear.


 
required
object (Money) 
The currency and amount for a financial transaction, such as a balance or payment due.


 
{
  • "note": "string",
  • "capture_type": "OUTSTANDING_BALANCE",
  • "amount": {
    • "currency_code": "str",
    • "value": "string"
    }
}
subscription_request
The create subscription request details.


plan_id
required
string  = 26 characters ^P-[A-Z0-9]*$
The ID of the plan.


 
quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The quantity of the product in the subscription.


 
auto_renewal
boolean
 Default:  false
DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.


 
custom_id
string  [ 1 .. 127 ] characters ^[\x20-\x7E]+
The custom id for the subscription. Can be invoice id.


 
start_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
 Default:  "Current time"
The date and time when the subscription started, in Internet date and time format.


 
object (Money) 
The shipping charges.


 
object <payer_v1>  (subscriber_request) 
The subscriber request information .


 
object (application_context) 
The application context, which customizes the payer experience during the subscription approval process with PayPal.


 
object (plan_override) 
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.


 
{
  • "plan_id": "stringstringstringstringst",
  • "quantity": "string",
  • "auto_renewal": false,
  • "custom_id": "string",
  • "start_time": "string",
  • "shipping_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "subscriber": {
    • "email_address": "string",
    • "payer_id": "stringstrings",
    • "name": {
      • "given_name": "string",
      • "surname": "string"
      },
    • "phone": {
      • "phone_type": "FAX",
      • "phone_number": {
        • "national_number": "string"
        }
      },
    • "shipping_address": {
      • "type": "SHIPPING",
      • "name": {
        • "full_name": "string"
        },
      • "address": {
        • "address_line_1": "string",
        • "address_line_2": "string",
        • "admin_area_2": "string",
        • "admin_area_1": "string",
        • "postal_code": "string",
        • "country_code": "st"
        }
      },
    • "payment_source": {
      • "card": {
        • "name": "string",
        • "number": "stringstrings",
        • "security_code": "string",
        • "expiry": "strings",
        • "billing_address": {
          • "address_line_1": "string",
          • "address_line_2": "string",
          • "admin_area_2": "string",
          • "admin_area_1": "string",
          • "postal_code": "string",
          • "country_code": "st"
          }
        }
      }
    },
  • "application_context": {
    • "brand_name": "string",
    • "shipping_preference": "GET_FROM_FILE",
    • "user_action": "CONTINUE",
    • "return_url": "http://example.com",
    • "cancel_url": "http://example.com",
    • "locale": "string",
    • "payment_method": {
      • "payer_selected": "PAYPAL",
      • "payee_preferred": "UNRESTRICTED"
      }
    },
  • "plan": {
    • "billing_cycles": [
      • {
        • "sequence": 1,
        • "total_cycles": 999,
        • "pricing_scheme": {
          • "version": 999,
          • "pricing_model": "VOLUME",
          • "tiers": [
            • {
              • "starting_quantity": "string",
              • "ending_quantity": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              }
            ],
          • "fixed_price": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "create_time": "string",
          • "update_time": "string"
          }
        }
      ],
    • "payment_preferences": {
      • "auto_bill_outstanding": true,
      • "setup_fee_failure_action": "CONTINUE",
      • "payment_failure_threshold": 999,
      • "setup_fee": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "taxes": {
      • "inclusive": true,
      • "percentage": "string"
      }
    }
}
subscription_revise_request
The request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the shipping_amount and shipping_address values for the subscription. This type of update requires the buyer's consent.


plan_id
string  = 26 characters ^P-[A-Z0-9]*$
The unique PayPal-generated ID for the plan.


 
quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The quantity of the product or service in the subscription.


 
object (Money) 
The shipping charges.


 
object (shipping_detail) 
The shipping address of the subscriber.


 
object (application_context) 
The application context, which customizes the payer experience during the subscription approval process with PayPal.


 
object (plan_override) 
An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object. Any existing overrides will not be carried forward during subscription revise.


 
{
  • "plan_id": "stringstringstringstringst",
  • "quantity": "string",
  • "shipping_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_address": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "application_context": {
    • "brand_name": "string",
    • "shipping_preference": "GET_FROM_FILE",
    • "return_url": "http://example.com",
    • "cancel_url": "http://example.com",
    • "locale": "string",
    • "payment_method": {
      • "payer_selected": "PAYPAL",
      • "payee_preferred": "UNRESTRICTED"
      }
    },
  • "plan": {
    • "billing_cycles": [
      • {
        • "sequence": 1,
        • "total_cycles": 999,
        • "pricing_scheme": {
          • "version": 999,
          • "pricing_model": "VOLUME",
          • "tiers": [
            • {
              • "starting_quantity": "string",
              • "ending_quantity": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              }
            ],
          • "fixed_price": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "create_time": "string",
          • "update_time": "string"
          }
        }
      ],
    • "payment_preferences": {
      • "auto_bill_outstanding": true,
      • "setup_fee_failure_action": "CONTINUE",
      • "payment_failure_threshold": 999,
      • "setup_fee": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "taxes": {
      • "inclusive": true,
      • "percentage": "string"
      }
    }
}
subscription_revise_request
The request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the shipping_amount and shipping_address values for the subscription. This type of update requires the buyer's consent.


plan_id
string  = 26 characters ^P-[A-Z0-9]*$
The unique PayPal-generated ID for the plan.


 
quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The quantity of the product or service in the subscription.


 
object (Money) 
The shipping charges.


 
object (shipping_detail) 
The shipping address of the subscriber.


 
object (plan_override) 
An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object. Any existing overrides will not be carried forward during subscription revise.


 
{
  • "plan_id": "stringstringstringstringst",
  • "quantity": "string",
  • "shipping_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_address": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "plan": {
    • "billing_cycles": [
      • {
        • "sequence": 1,
        • "total_cycles": 999,
        • "pricing_scheme": {
          • "version": 999,
          • "pricing_model": "VOLUME",
          • "tiers": [
            • {
              • "starting_quantity": "string",
              • "ending_quantity": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              }
            ],
          • "fixed_price": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "create_time": "string",
          • "update_time": "string"
          }
        }
      ],
    • "payment_preferences": {
      • "auto_bill_outstanding": true,
      • "setup_fee_failure_action": "CONTINUE",
      • "payment_failure_threshold": 999,
      • "setup_fee": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "taxes": {
      • "inclusive": true,
      • "percentage": "string"
      }
    }
}
subscription_revise_response
The response to a request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the shipping_amount and shipping_address values for the subscription. This type of update requires the buyer's consent.


plan_id
string  = 26 characters ^P-[A-Z0-9]*$
The unique PayPal-generated ID for the plan.


 
quantity
string  [ 1 .. 32 ] characters ^([0-9]+|([0-9]+)?[.][0-9]+)$
The quantity of the product or service in the subscription.


 
object (Money) 
The shipping charges.


 
object (shipping_detail) 
The shipping address of the subscriber.


 
object (plan_override) 
An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object. Any existing overrides will not be carried forward during subscription revise.


 
plan_overridden
boolean
Indicates whether the subscription has overridden any plan attributes.


 
Array of objects (Link Description) 
An array of request-related HATEOAS links.


 
{
  • "plan_id": "stringstringstringstringst",
  • "quantity": "string",
  • "shipping_amount": {
    • "currency_code": "str",
    • "value": "string"
    },
  • "shipping_address": {
    • "type": "SHIPPING",
    • "name": {
      • "full_name": "string"
      },
    • "address": {
      • "address_line_1": "string",
      • "address_line_2": "string",
      • "admin_area_2": "string",
      • "admin_area_1": "string",
      • "postal_code": "string",
      • "country_code": "st"
      }
    },
  • "plan": {
    • "billing_cycles": [
      • {
        • "sequence": 1,
        • "total_cycles": 999,
        • "pricing_scheme": {
          • "version": 999,
          • "pricing_model": "VOLUME",
          • "tiers": [
            • {
              • "starting_quantity": "string",
              • "ending_quantity": "string",
              • "amount": {
                • "currency_code": null,
                • "value": null
                }
              }
            ],
          • "fixed_price": {
            • "currency_code": "str",
            • "value": "string"
            },
          • "create_time": "string",
          • "update_time": "string"
          }
        }
      ],
    • "payment_preferences": {
      • "auto_bill_outstanding": true,
      • "setup_fee_failure_action": "CONTINUE",
      • "payment_failure_threshold": 999,
      • "setup_fee": {
        • "currency_code": "str",
        • "value": "string"
        }
      },
    • "taxes": {
      • "inclusive": true,
      • "percentage": "string"
      }
    },
  • "plan_overridden": true,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
subscription_status
The subscription status details.


status
string  [ 1 .. 24 ] characters ^[A-Z_]+$
The status of the subscription.


 Enum Value Description
APPROVAL_PENDING
The subscription is created but not yet approved by the buyer.


APPROVED
The buyer has approved the subscription.


ACTIVE
The subscription is active.


SUSPENDED
The subscription is suspended.


CANCELLED
The subscription is cancelled.


EXPIRED
The subscription is expired.


 
status_change_note
string  [ 1 .. 128 ] characters ^.*$
The reason or notes for the status of the subscription.


 
status_update_time
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time, in Internet date and time format. Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.


 
{
  • "status": "APPROVAL_PENDING",
  • "status_change_note": "string",
  • "status_update_time": "string"
}
subscription_suspend_request
The suspend subscription request details.


reason
required
string  [ 1 .. 128 ] characters ^.*$
The reason for suspension of the Subscription.


 
{
  • "reason": "string"
}
tax_info
The tax ID of the customer. The customer is also known as the payer. Both tax_id and tax_id_type are required.


tax_id
required
string  <= 14 characters 
The customer's tax ID value.


 
tax_id_type
required
string
The customer's tax ID type.


 Enum Value Description
BR_CPF
The individual tax ID type, typically is 11 characters long.


BR_CNPJ
The business tax ID type, typically is 14 characters long.


 
{
  • "tax_id": "string",
  • "tax_id_type": "BR_CPF"
}
taxes
The tax details.


inclusive
boolean
 Default:  true
Indicates whether the tax was already included in the billing amount.


 
percentage
required
string <ppaas_common_percentage_v2>  (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The tax percentage on the billing amount.


 
{
  • "inclusive": true,
  • "percentage": "string"
}
taxes_override
The tax details.


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


 
percentage
string <ppaas_common_percentage_v2>  (percentage) ^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$
The tax percentage on the billing amount.


 
{
  • "inclusive": true,
  • "percentage": "string"
}
three_d_secure_authentication_response
Results of 3D Secure Authentication.


authentication_status
string (pares_status)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
The outcome of the issuer's authentication.


 Enum Value Description
Y
Successful authentication.


N
Failed authentication / account not verified / transaction denied.


U
Unable to complete authentication.


A
Successful attempts transaction.


C
Challenge required for authentication.


R
Authentication rejected (merchant must not submit for authorization).


D
Challenge required; decoupled authentication confirmed.


I
Informational only; 3DS requestor challenge preference acknowledged.


 
enrollment_status
string (enrolled)   [ 1 .. 255 ] characters ^[0-9A-Z_]+$
Status of authentication eligibility.


 Enum Value Description
Y
Yes. The bank is participating in 3-D Secure protocol and will return the ACSUrl.


N
No. The bank is not participating in 3-D Secure protocol.


U
Unavailable. The DS or ACS is not available for authentication at the time of the request.


B
Bypass. The merchant authentication rule is triggered to bypass authentication.


 
{
  • "authentication_status": "Y",
  • "enrollment_status": "Y"
}
transaction
The transaction details.


status
string
The status of the captured payment.


 Enum Value Description
COMPLETED
The funds for this captured payment were credited to the payee's PayPal account.


DECLINED
The funds could not be captured.


PARTIALLY_REFUNDED
An amount less than this captured payment's amount was partially refunded to the payer.


PENDING
The funds for this captured payment was not yet credited to the payee's PayPal account. For more information, see status.details.


REFUNDED
An amount greater than or equal to this captured payment's amount was refunded to the payer.


 
id
required
string  [ 3 .. 50 ] characters 
The PayPal-generated transaction ID.


 
required
object (amount_with_breakdown) 
The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.


 
object (Name) 
The name of the customer.


 
payer_email
string <ppaas_common_email_address_v2>  (email_address)   [ 3 .. 254 ] characters ^.+@[^"\-].+$
The email ID of the customer.


 
time
required
string <ppaas_date_time_v3>  (date_time)   [ 20 .. 64 ] characters ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|...
The date and time when the transaction was processed, in Internet date and time format.


 
{
  • "status": "COMPLETED",
  • "id": "string",
  • "amount_with_breakdown": {
    • "gross_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "total_item_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "fee_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "shipping_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "tax_amount": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "net_amount": {
      • "currency_code": "str",
      • "value": "string"
      }
    },
  • "payer_name": {
    • "prefix": "string",
    • "given_name": "string",
    • "surname": "string",
    • "middle_name": "string",
    • "suffix": "string",
    • "alternate_full_name": "string",
    • "full_name": "string"
    },
  • "payer_email": "string",
  • "time": "string"
}
transactions_list
The list transactions for a subscription request details.


Array of objects (transaction)   [ 0 .. 32767 ] items 
An array of transactions.


 
total_items
integer  [ 0 .. 500000000 ] 
The total number of items.


 
total_pages
integer  [ 0 .. 100000000 ] 
The total number of pages.


 
Array of objects (Link Description)   [ 1 .. 10 ] items 
An array of request-related HATEOAS links.


 
{
  • "transactions": [
    • {
      • "status": "COMPLETED",
      • "id": "string",
      • "amount_with_breakdown": {
        • "gross_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "total_item_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "fee_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "shipping_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "tax_amount": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "net_amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        },
      • "payer_name": {
        • "prefix": "string",
        • "given_name": "string",
        • "surname": "string",
        • "middle_name": "string",
        • "suffix": "string",
        • "alternate_full_name": "string",
        • "full_name": "string"
        },
      • "payer_email": "string",
      • "time": "string"
      }
    ],
  • "total_items": 500000000,
  • "total_pages": 100000000,
  • "links": [
    • {
      • "href": "string",
      • "rel": "string",
      • "method": "GET"
      }
    ]
}
update_pricing_scheme_request
The update pricing scheme request details.


billing_cycle_sequence
required
integer  [ 1 .. 99 ] 
The billing cycle sequence.


 
required
object (pricing_scheme) 
The pricing scheme details.


 
{
  • "billing_cycle_sequence": 1,
  • "pricing_scheme": {
    • "version": 999,
    • "pricing_model": "VOLUME",
    • "tiers": [
      • {
        • "starting_quantity": "string",
        • "ending_quantity": "string",
        • "amount": {
          • "currency_code": "str",
          • "value": "string"
          }
        }
      ],
    • "fixed_price": {
      • "currency_code": "str",
      • "value": "string"
      },
    • "create_time": "string",
    • "update_time": "string"
    }
}
update_pricing_schemes_list_request
The update pricing scheme request details.


required
Array of objects (update_pricing_scheme_request)   [ 1 .. 99 ] items 
An array of pricing schemes.


 
{
  • "pricing_schemes": [
    • {
      • "billing_cycle_sequence": 1,
      • "pricing_scheme": {
        • "version": 999,
        • "pricing_model": "VOLUME",
        • "tiers": [
          • {
            • "starting_quantity": "string",
            • "ending_quantity": "string",
            • "amount": {
              • "currency_code": "str",
              • "value": "string"
              }
            }
          ],
        • "fixed_price": {
          • "currency_code": "str",
          • "value": "string"
          },
        • "create_time": "string",
        • "update_time": "string"
        }
      }
    ]
}