Subscriptions API
Plans (resource group)
/billing/plans
resource to create and manage plans.
Create plan
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
. -
Prefer
string
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 theid
,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. For more information about PayPal-Request-Id, see PayPal-Request-Id.
Request body
-
product_id
string
required
The ID of the product. -
name
string
required
The plan name. -
status
enum
The initial state of the plan. Allowed input values are CREATED and ACTIVE. The allowed values are: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
The detailed description of the plan. -
An array of billing cycles for trial and regular billing. A plan can have multiple billing cycles but only one trial billing cycle.
-
The payment preferences for a subscription.
-
taxes
The tax details. -
quantity_supported
boolean
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: PLAN-18062019-001" \
-d '{
"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": 1,
"pricing_scheme": {
"fixed_price": {
"value": "10",
"currency_code": "USD"
}
}
},
{
"frequency": {
"interval_unit": "MONTH",
"interval_count": 1
},
"tenure_type": "REGULAR",
"sequence": 2,
"total_cycles": 12,
"pricing_scheme": {
"fixed_price": {
"value": "100",
"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
201 Created
status code and a JSON response body that shows billing plan details.-
id
string
The unique PayPal-generated ID for the plan. -
product_id
string
The ID for the product. -
name
string
The plan name. -
status
enum
The plan status. The possible values are: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
The detailed description of the plan. -
billing_cycles
array (contains the billing_cycle object)
An array of billing cycles for trial and regular billing. A plan can have multiple billing cycles but only one trial billing cycle. -
payment_preferences
The payment preferences for a subscription. -
taxes
The tax details. -
quantity_supported
boolean
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service. -
create_time
The date and time when the plan was created, in Internet date and time format. -
update_time
The date and time when the plan was last updated, in Internet date and time format. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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": 1,
"pricing_scheme": {
"fixed_price": {
"value": "10",
"currency_code": "USD"
},
"status": "ACTIVE",
"version": 1,
"create_time": "2018-12-10T21:20:49Z",
"update_time": "2018-12-10T21:20:49Z"
}
},
{
"frequency": {
"interval_unit": "MONTH",
"interval_count": 1
},
"tenure_type": "REGULAR",
"sequence": 2,
"total_cycles": 12,
"pricing_scheme": {
"fixed_price": {
"value": "100",
"currency_code": "USD"
},
"status": "ACTIVE",
"version": 1,
"create_time": "2018-12-10T21:20:49Z",
"update_time": "2018-12-10T21:20:49Z"
}
}
],
"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": "2018-12-10T21:20:49Z",
"update_time": "2018-12-10T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
"rel": "edit",
"method": "PATCH"
},
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/deactivate",
"rel": "deactivate",
"method": "POST"
},
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/update-pricing-schemes",
"rel": "edit",
"method": "POST"
}
]
}
List plans
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
. -
Prefer
string
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 theid
,name
,description
and HATEOAS links.return=representation
. The server returns a complete resource representation, including the current state of the resource.
Query parameters
-
product_id
string
Filters the response by a Product ID. -
plan_ids
string
Filters the response by list of plan IDs. Filter supports upto 10 plan IDs. -
page_size
integer
The number of items to return in the response. -
page
integer
A non-zero integer which is the start index of the entire list of items to return in the response. The combination ofpage=1
andpage_size=20
returns the first 20 items. The combination ofpage=2
andpage_size=20
returns the next 20 items. -
total_required
boolean
Indicates whether to show the total count in the response.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/billing/plans?product_id=PROD-XXCD1234QWER65782&page_size=2&page=1&total_required=true \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that lists billing plans.-
plans
array (contains the plan object)
An array of plans. -
total_items
integer
The total number of items. -
total_pages
integer
The total number of pages. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"total_items": 12,
"total_pages": 6,
"plans": [
{
"id": "P-5ML4271244454362WXNWU5NQ",
"product_id": "PROD-XXCD1234QWER65782",
"status": "ACTIVE",
"name": "Zoho Marketing Campaign Plan",
"description": "Zoho Marketing Campaign Plan",
"create_time": "2018-12-10T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
"rel": "self",
"method": "GET"
}
]
},
{
"id": "P-6LL4271454454362WXNWU5NQ",
"product_id": "PROD-XXCD1234QWER65782",
"status": "ACTIVE",
"name": "Zoho Marketing Campaign Basic Plan",
"description": "Zoho Marketing Campaign Plan",
"create_time": "2019-01-10T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v1/billing/plans/P-6LL4271454454362WXNWU5NQ",
"rel": "self",
"method": "GET"
}
]
}
],
"links": [
{
"href": "https://api.paypal.com/v1/billing/plans?product_id=PROD-XXCD1234QWER65782&page_size=2&page=1",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v1/billing/plans?product_id=PROD-XXCD1234QWER65782&page_size=2&page=1",
"rel": "first",
"method": "GET"
},
{
"href": "https://api.paypal.com/v1/billing/plans?product_id=PROD-XXCD1234QWER65782&page_size=2&page=2",
"rel": "next",
"method": "GET"
},
{
"href": "https://api.paypal.com/v1/billing/plans?product_id=PROD-XXCD1234QWER65782&page_size=2&page=6",
"rel": "last",
"method": "GET"
}
]
}
Update plan
CREATED
or ACTIVE
status. For an INACTIVE
plan, you can make only status updates.You can patch these attributes and objects:
Attribute or object | Operations |
---|---|
description | replace |
payment_preferences.auto_bill_outstanding | replace |
taxes.percentage | replace |
payment_preferences.payment_failure_threshold | replace |
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
plan_id
string
required
The ID of the plan.
Request body
-
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
Sample Request
curl -v -X PATCH https://api.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
{
"op": "replace",
"path": "/payment_preferences/payment_failure_threshold",
"value": 7
}
]'
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Show plan details
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
plan_id
string
required
The ID of the plan.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that shows plan details.-
id
string
The unique PayPal-generated ID for the plan. -
product_id
string
The ID for the product. -
name
string
The plan name. -
status
enum
The plan status. The possible values are: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
The detailed description of the plan. -
billing_cycles
array (contains the billing_cycle object)
An array of billing cycles for trial and regular billing. A plan can have multiple billing cycles but only one trial billing cycle. -
payment_preferences
The payment preferences for a subscription. -
taxes
The tax details. -
quantity_supported
boolean
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service. -
create_time
The date and time when the plan was created, in Internet date and time format. -
update_time
The date and time when the plan was last updated, in Internet date and time format. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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": 1
},
{
"frequency": {
"interval_unit": "MONTH",
"interval_count": 1
},
"tenure_type": "REGULAR",
"sequence": 2,
"total_cycles": 12,
"pricing_scheme": {
"fixed_price": {
"value": "10",
"currency_code": "USD"
},
"status": "ACTIVE",
"version": 1,
"create_time": "2018-12-10T21:20:49Z",
"update_time": "2018-12-10T21:20:49Z"
}
}
],
"taxes": {
"percentage": "10",
"inclusive": false
},
"create_time": "2018-12-10T21:20:49Z",
"update_time": "2018-12-10T21:20:49Z",
"links": [
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ",
"rel": "edit",
"method": "PATCH"
},
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/deactivate",
"rel": "deactivate",
"method": "POST"
},
{
"href": "https://api.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/update-pricing-schemes",
"rel": "edit",
"method": "POST"
}
]
}
Activate plan
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
plan_id
string
required
The ID of the plan.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ/activate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Deactivate plan
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
plan_id
string
required
The ID of the plan.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ/deactivate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Update pricing
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
plan_id
string
required
The ID for the plan.
Request body
-
An array of pricing schemes.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans/P-2UF78835G6983425GLSM44MA/update-pricing-schemes \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"pricing_schemes": [
{
"billing_cycle_sequence": 2,
"pricing_scheme": {
"fixed_price": {
"value": "50",
"currency_code": "USD"
}
}
}
]
}'
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Subscriptions (resource group)
/billing/subscriptions
resource to create and manage subscriptions.
Create subscription
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
. -
Prefer
string
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 theid
,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. For more information about PayPal-Request-Id, see PayPal-Request-Id.
Request body
-
plan_id
string
required
The ID of the plan. -
start_time
The date and time when the subscription started, in Internet date and time format. -
quantity
string
The quantity of the product in the subscription. -
shipping_amount
The shipping charges. -
subscriber
The subscriber information. -
auto_renewal
boolean
DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete. -
application_context
The application context, which customizes the payer experience during the subscription approval process with PayPal.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: SUBSCRIPTION-21092019-001" \
-d '{
"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
201 Created
status code and a JSON response body that shows subscription details.-
status
enum
The status of the subscription. The possible values are: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
The reason or notes for the status of the subscription. -
status_update_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.
-
id
string
The PayPal-generated ID for the subscription. -
plan_id
string
The ID of the plan. -
start_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.
-
quantity
string
The quantity of the product in the subscription. -
shipping_amount
The currency and amount for a financial transaction, such as a balance or payment due. -
subscriber
The subscriber information. -
billing_info
The billing details for the subscription. If the subscription was or is active, these fields are populated. -
create_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.
-
update_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.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"id": "I-BW452GLLEP1G",
"status": "APPROVAL_PENDING",
"status_update_time": "2018-12-10T21:20:49Z",
"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"
}
}
},
"create_time": "2018-12-10T21:20:49Z",
"links": [
{
"href": "https://www.paypal.com/webapps/billing/subscriptions?ba_token=BA-2M539689T3856352J",
"rel": "approve",
"method": "GET"
},
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
"rel": "edit",
"method": "PATCH"
},
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
"rel": "self",
"method": "GET"
}
]
}
Update subscription
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
subscription_id
string
required
The ID for the subscription.
Request body
-
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
Sample Request
curl -v -X PATCH https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '[
{
"op": "replace",
"path": "/billing_info/outstanding_balance",
"value": {
"currency_code": "USD",
"value": "50.00"
}
}
]'
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Show subscription details
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
subscription_id
string
required
The ID of the subscription.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that shows subscription details.-
status
enum
The status of the subscription. The possible values are: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
The reason or notes for the status of the subscription. -
status_update_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.
-
id
string
The PayPal-generated ID for the subscription. -
plan_id
string
The ID of the plan. -
start_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.
-
quantity
string
The quantity of the product in the subscription. -
shipping_amount
The currency and amount for a financial transaction, such as a balance or payment due. -
subscriber
The subscriber information. -
billing_info
The billing details for the subscription. If the subscription was or is active, these fields are populated. -
create_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.
-
update_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.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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"
},
"billing_info": {
"outstanding_balance": {
"currency_code": "USD",
"value": "1.0"
},
"cycle_executions": [
{
"tenure_type": "TRIAL",
"sequence": 1,
"cycles_completed": 0,
"cycles_remaining": 1,
"total_cycles": 1
},
{
"tenure_type": "REGULAR",
"sequence": 2,
"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": [
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/cancel",
"rel": "cancel",
"method": "POST"
},
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
"rel": "edit",
"method": "PATCH"
},
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/suspend",
"rel": "suspend",
"method": "POST"
},
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/capture",
"rel": "capture",
"method": "POST"
}
],
"status": "ACTIVE",
"status_update_time": "2019-04-09T10:27:27Z"
}
Activate subscription
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
subscription_id
string
required
The ID of the subscription.
Request body
-
reason
string
The reason for activation of a subscription. Required to reactivate the subscription.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/activate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"reason": "Reactivating the subscription"
}'
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Cancel subscription
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
subscription_id
string
required
The ID of the subscription.
Request body
-
reason
string
required
The reason for the cancellation of a subscription.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/cancel \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"reason": "Not satisfied with the service"
}'
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
Capture authorized payment on subscription
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
. -
PayPal-Request-Id
string
The server stores keys for 72 hours. For more information about PayPal-Request-Id, see PayPal-Request-Id.
Path parameters
-
subscription_id
string
required
The ID of the subscription.
Request body
-
note
string
required
The reason or note for the subscription charge. -
capture_type
enum
required
The type of capture. The allowed values are:OUTSTANDING_BALANCE
. The outstanding balance that the subscriber must clear.
-
The amount of the outstanding balance. This value cannot be greater than the current outstanding balance amount.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-H "PayPal-Request-Id: CAPTURE-160919-A0051" \
-d '{
"note": "Charging as the balance reached the limit",
"capture_type": "OUTSTANDING_BALANCE",
"amount": {
"currency_code": "USD",
"value": "100"
}
}'
Response
-
status
enum
The status of the captured payment. The possible values are: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, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
-
id
string
The PayPal-generated transaction ID. -
amount_with_breakdown
The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts. -
payer_name
The name of the customer. -
payer_email
The email ID of the customer. -
time
The date and time when the transaction was processed, in Internet date and time format.
Sample Response
202 Accepted
Update quantity of product or service in subscription
shipping_amount
, shipping_address
values for the subscription. This type of update requires the buyer's consent.
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
subscription_id
string
required
The ID of the subscription.
Request body
-
plan_id
string
The unique PayPal-generated ID for the plan. -
quantity
string
The quantity of the product or service in the subscription. -
shipping_amount
The shipping charges. -
shipping_address
The shipping address of the subscriber. -
application_context
The application context, which customizes the payer experience during the subscription approval process with PayPal.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/revise \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"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": {
"brand_name": "walmart",
"locale": "en-US",
"shipping_preference": "SET_PROVIDED_ADDRESS",
"payment_method": {
"payer_selected": "PAYPAL",
"payee_preferred": "IMMEDIATE_PAYMENT_REQUIRED"
},
"return_url": "https://example.com/returnUrl",
"cancel_url": "https://example.com/cancelUrl"
}
}'
Response
200 OK
status code and a JSON response body that shows subscription details.-
plan_id
string
The unique PayPal-generated ID for the plan. -
quantity
string
The quantity of the product or service in the subscription. -
effective_time
The date and time when this change is effective, in Internet date and time format. Defaults to the current time. -
shipping_amount
The shipping charges. -
shipping_address
The shipping address of the subscriber. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"plan_id": "P-5ML4271244454362WXNWU5NQ",
"effective_time": "2018-11-01T00:00:00Z",
"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"
}
},
"links": [
{
"href": "https://www.paypal.com/webapps/billing/subscriptions/update?ba_token=BA-2M539689T3856352J",
"rel": "approve",
"method": "GET"
}
]
}
Suspend subscription
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
subscription_id
string
required
The ID of the subscription.
Request body
-
reason
string
required
The reason for suspenson of the subscription.
Sample Request
curl -v -X POST https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/suspend \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token" \
-d '{
"reason": "Item out of stock"
}'
Response
204 No Content
status code with no JSON response body.Sample Response
204 No Content
List transactions for subscription
Header parameters
-
Authorization
string
required
To make REST API calls, include the bearer token in theAuthorization
header with theBearer
authentication scheme. The value isBearer <Access-Token>
orBasic <client_id>:<secret>
. -
Content-Type
string
required
The media type. Required for operations with a request body. The value isapplication/<format>
, where theformat
isjson
.
Path parameters
-
subscription_id
string
required
The ID of the subscription.
Query parameters
-
start_time
string
required
The start time of the range of transactions to list. -
end_time
string
required
The end time of the range of transactions to list.
Sample Request
curl -v -X GET https://api.sandbox.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/transactions?start_time=2018-01-21T07:50:20.940Z&end_time=2018-08-21T07:50:20.940Z \
-H "Content-Type: application/json" \
-H "Authorization: Bearer Access-Token"
Response
200 OK
status code and a JSON response body that shows subscription details.-
transactions
array (contains the transaction object)
An array of transactions. -
total_items
integer
The total number of items. -
total_pages
integer
The total number of pages. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
Sample Response
{
"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": [
{
"href": "https://api.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/transactions?start_time=2018-01-21T07:50:20.940Z&end_time=2018-08-21T07:50:20.940Z",
"rel": "self",
"method": "GET"
}
]
}
Common object definitions
address_details
-
street_number
string
The street number. -
street_name
string
The street name. JustDrury
inDrury Lane
. -
street_type
string
The street type. For example, avenue, boulevard, road, or expressway. -
delivery_service
string
The delivery service. Post office box, bag number, or post office name. -
building_name
string
A named locations that represents the premise. Usually a building name or number or collection of buildings with a common name or number. For example,Craven House
. -
sub_building
string
The first-order entity below a named building or location that represents the sub-premise. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.
address_portable
-
address_line_1
string
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
The second line of the address. For example, suite or apartment number. -
address_line_3
string
The third line of the address, if needed. For example, a street complement for Brazil, direction text, such asnext to Walmart
, or a landmark in an Indian address. -
admin_area_4
string
The neighborhood, ward, or district. Smaller thanadmin_area_level_3
orsub_locality
. Value is:- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
-
admin_area_3
string
A sub-locality, suburb, neighborhood, or district. Smaller thanadmin_area_level_2
. Value is:- Brazil. Suburb, bairro, or neighborhood.
- India. Sub-locality or district. Street name information is not always available but a sub-locality or district can be a very small area.
-
admin_area_2
string
A city, town, or village. Smaller thanadmin_area_level_1
. -
admin_area_1
string
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 notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
-
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. -
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions. -
address_details
The non-portable additional address details that are sometimes needed for compliance, risk, or other scenarios where fine-grain address information might be needed. Not portable with common third party and open source. Redundant with core fields.
For example,address_portable.address_line_1
is usually a combination ofaddress_details.street_number
,street_name
, andstreet_type
.
address_portable_postal_code_validation
-
address_portable_postal_code_validation
amount_with_breakdown
-
The amount for this transaction.
-
fee_amount
The fee details for the transaction. -
shipping_amount
The shipping amount for the transaction. -
tax_amount
The tax amount for the transaction. -
The net amount that the payee receives for this transaction in their PayPal account. The net amount is computed as
gross_amount
minus thepaypal_fee
.
application_context
-
brand_name
string
The label that overrides the business name in the PayPal account on the PayPal site. -
locale
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
, orzh-TW
. -
shipping_preference
enum
The location from which the shipping address is derived. The possible values are: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
enum
Configures the label name toContinue
orSubscribe Now
for subscription consent experience. The possible values are: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.
-
payment_method
The customer and merchant payment preferences. Currently only PAYPAL payment method is supported. -
return_url
string
required
The URL where the customer is redirected after the customer approves the payment. -
cancel_url
string
required
The URL where the customer is redirected after the customer cancels the payment.
billing_cycle
-
pricing_scheme
The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme. -
The frequency details for this billing cycle.
-
tenure_type
enum
required
The tenure type of the billing cycle. In case of a plan having trial period, only 1 trial period is allowed per plan. The possible values are:REGULAR
. A regular billing cycle.TRIAL
. A trial billing cycle.
-
sequence
integer
required
The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has asequence
of1
while a regular billing cycle has asequence
of2
, so that trial cycle runs before the regular cycle. -
total_cycles
integer
The number of times this billing cycle runs. Trial billing cycles can only have a value of1
fortotal_cycles
. Regular billing cycles can either have infinite cycles (value of0
fortotal_cycles
) or a finite number of cycles (value between1
and999
fortotal_cycles
).
capture_status
-
status
enum
The status of the captured payment. The possible values are: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, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
capture_status
-
status
enum
The status of the captured payment. The possible values are: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, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
-
status_details
The details of the captured payment status.
capture_status_details
-
reason
enum
The reason why the captured payment status isPENDING
orDENIED
. The possible values are: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.
country_code
-
country_code
string
The two-character ISO 3166-1 code that identifies the country or region.Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
currency_code
-
currency_code
string
The three-character ISO-4217 currency code that identifies the currency.
cycle_execution
-
tenure_type
enum
required
The type of the billing cycle. The possible values are:REGULAR
. A regular billing cycle.TRIAL
. A trial billing cycle.
-
sequence
integer
required
The order in which to run this cycle among other billing cycles. -
cycles_completed
integer
required
The number of billing cycles that have completed. -
cycles_remaining
integer
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
The active pricing scheme version for the billing cycle. -
total_cycles
integer
The number of times this billing cycle runs. Trial billing cycles can only have a value of1
fortotal_cycles
. Regular billing cycles can either have infinite cycles (value of0
fortotal_cycles
) or a finite number of cycles (value between1
and999
fortotal_cycles
).
date_no_time
-
date_no_time
string
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 standarddate_time
type. This regular expression does not validate all dates. For example, February 31 is valid and nothing is known about leap years.
date_time
-
date_time
string
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.
-
email
string
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.
email_address
-
email_address
string
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.
error
-
name
string
required
The human-readable, unique name of the error. -
message
string
required
The message that describes the error. -
debug_id
string
required
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. -
details
array (contains the error_details object)
An array of additional details about the error. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
error_details
-
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
The location of the field that caused the error. Value isbody
,path
, orquery
. -
issue
string
required
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.
frequency
-
interval_unit
enum
required
The interval at which the subscription is charged or billed. The possible values are:DAY
. A daily billing cycle.WEEK
. A weekly billing cycle.MONTH
. A monthly billing cycle.YEAR
. A yearly billing cycle.
-
interval_count
integer
The number of intervals after which a subscriber is billed. For example, if theinterval_unit
isDAY
with aninterval_count
of2
, the subscription is billed once every two days. The following table lists the maximum allowed values for theinterval_count
for eachinterval_unit
:Interval unit
Maximum interval count DAY
365 WEEK
52 MONTH
12 YEAR
1
language
-
language
string
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.
last_payment_details
-
The last payment amount.
-
The date and time when the last payment was made, in Internet date and time format.
link_description
-
href
string
required
The complete target URL. To make the related call, combine the method with this URI Template-formatted link. For pre-processing, include the$
,(
, and)
characters. Thehref
is the key HATEOAS component that links a completed call with a subsequent call. -
rel
string
required
The link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link. See Link Relations. -
method
enum
The HTTP method required to make the related call.
money
-
The three-character ISO-4217 currency code that identifies the currency.
-
value
string
required
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.
- An integer for currencies like
name
-
prefix
string
The prefix, or title, to the party's name. -
given_name
string
When the party is a person, the party's given, or first, name. -
surname
string
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
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
The suffix for the party's name. -
alternate_full_name
string
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
When the party is a person, the party's full name.
name_validation
-
name_validation
patch
-
op
enum
required
The operation. The possible values are: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.
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 avalue
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 afrom
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, thefrom
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 afrom
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, thefrom
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 avalue
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 thevalue
value. For test,equal
indicates that the value at the target location and the value thatvalue
defines are of the same JSON type. The data type of the value determines how equality is defined:
For more information, see 4.6. test.Type Considered equal if both values strings Contain the same number of Unicode characters and their code points are byte-by-byte equal. numbers Are numerically equal. arrays Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules. objects Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules). literals ( false
,true
, andnull
)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.
-
path
string
The JSON Pointer to the target document location at which to complete the operation. -
value
number,integer,string,boolean,null,array,object
The value to apply. Theremove
operation does not require a value. -
from
string
The JSON Pointer to the target document location from which to move the value. Required for themove
operation.
patch_request
-
patch_request
array (contains the patch object)
An array of JSON patch objects to apply partial updates to resources.
payer
-
name
The name of the payer. Supports only thegiven_name
andsurname
properties. -
email_address
The email address of the payer. -
payer_id
The PayPal assigned ID for the payer. -
phone
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. Thephone.phone_number
supports onlynational_number
. -
birth_date
The birth date of the payer inYYYY-MM-DD
format. -
tax_info
The tax information of the payer. Required only for Brazilian payer's. Bothtax_id
andtax_id_type
are required. -
address
The address of the payer. Supports only theaddress_line_1
,address_line_2
,admin_area_1
,admin_area_2
,postal_code
, andcountry_code
properties. Also referred to as the billing address of the customer.
payer.address_portable
-
address_line_1
string
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
The second line of the address. For example, suite or apartment number. -
admin_area_2
string
A city, town, or village. Smaller thanadmin_area_level_1
. -
admin_area_1
string
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 notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
-
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. -
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
payer.name
-
given_name
string
When the party is a person, the party's given, or first, name. -
surname
string
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.
payer_id
-
payer_id
string
The PayPal payer ID, which is a masked version of the PayPal account number intended for use with third parties. The account number is reversibly encrypted and a proprietary variant of Base32 is used to encode the result.
payment_method
-
payer_selected
string
The customer-selected payment method on the merchant site. -
payee_preferred
enum
The merchant-preferred payment sources. The possible values are: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.
payment_preferences
-
auto_bill_outstanding
boolean
Indicates whether to automatically bill the outstanding amount in the next billing cycle. -
setup_fee
The initial set-up fee for the service. -
setup_fee_failure_action
enum
The action to take on the subscription if the initial payment for the setup fails. The possible values are: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
The maximum number of payment failures before a subscription is suspended. For example, ifpayment_failure_threshold
is2
, the subscription automatically updates to theSUSPEND
state if two consecutive payments fail.
percentage
-
percentage
string
The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as19.99
.
phone
-
country_code
string
required
The country calling code (CC), in its canonical international E.164 numbering plan format. The combined length of the CC and the national number must not be greater than 15 digits. The national number consists of a national destination code (NDC) and subscriber number (SN). -
national_number
string
required
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). -
extension_number
string
The extension number.
phone_type
-
phone_type
enum
The phone type.
phone_with_type
-
phone_type
enum
The phone type. -
The phone number, in its canonical international E.164 numbering plan format. Supports only the
national_number
property.
phone_with_type.phone
-
national_number
string
required
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).
plan
-
id
string
The unique PayPal-generated ID for the plan. -
product_id
string
The ID for the product. -
name
string
The plan name. -
status
enum
The plan status. The possible values are: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
The detailed description of the plan. -
billing_cycles
array (contains the billing_cycle object)
An array of billing cycles for trial and regular billing. A plan can have multiple billing cycles but only one trial billing cycle. -
payment_preferences
The payment preferences for a subscription. -
taxes
The tax details. -
quantity_supported
boolean
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service. -
create_time
The date and time when the plan was created, in Internet date and time format. -
update_time
The date and time when the plan was last updated, in Internet date and time format. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
plan_collection
-
plans
array (contains the plan object)
An array of plans. -
total_items
integer
The total number of items. -
total_pages
integer
The total number of pages. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
plan_request
-
product_id
string
required
The ID of the product. -
name
string
required
The plan name. -
status
enum
The initial state of the plan. Allowed input values are CREATED and ACTIVE. The possible values are: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
The detailed description of the plan. -
An array of billing cycles for trial and regular billing. A plan can have multiple billing cycles but only one trial billing cycle.
-
The payment preferences for a subscription.
-
taxes
The tax details. -
quantity_supported
boolean
Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.
pricing_scheme
-
version
integer
The version of the pricing scheme. -
fixed_price
The fixed amount to charge for the subscription. For regular pricing, it is limited to a 20% increase from the current amount and the change is applicable for both existing and future subscriptions. For trial period pricing, there is no limit or constraint in changing the amount and the change is applicable only on future subscriptions. -
create_time
The date and time when this pricing scheme was created, in Internet date and time format. -
update_time
The date and time when this pricing scheme was last updated, in Internet date and time format.
shipping_detail
shipping_detail.address_portable
-
address_line_1
string
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
The second line of the address. For example, suite or apartment number. -
admin_area_2
string
A city, town, or village. Smaller thanadmin_area_level_1
. -
admin_area_1
string
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 notCalifornia
. Value, by country, is:- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
-
postal_code
string
The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See postal code. -
The two-character ISO 3166-1 code that identifies the country or region.
Note: The country code for Great Britain is
GB
and notUK
as used in the top-level domain names for that country. Use theC2
country code for China worldwide for comparable uncontrolled price (CUP) method, bank card, and cross-border transactions.
shipping_detail.name
-
full_name
string
When the party is a person, the party's full name.
subscription
-
status
enum
The status of the subscription. The possible values are: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
The reason or notes for the status of the subscription. -
status_update_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.
-
id
string
The PayPal-generated ID for the subscription. -
plan_id
string
The ID of the plan. -
start_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.
-
quantity
string
The quantity of the product in the subscription. -
shipping_amount
The currency and amount for a financial transaction, such as a balance or payment due. -
subscriber
The subscriber information. -
billing_info
The billing details for the subscription. If the subscription was or is active, these fields are populated. -
create_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.
-
update_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.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links.
subscription_activate_request
-
reason
string
The reason for activation of a subscription. Required to reactivate the subscription.
subscription_billing_info
-
The total pending bill amount, to be paid by the subscriber.
-
cycle_executions
array (contains the cycle_execution object)
The trial and regular billing executions. -
last_payment
The details for the last payment of the subscription. -
next_billing_time
The next date and time for billing this subscription, in Internet date and time format. -
final_payment_time
The date and time when the final billing cycle occurs, in Internet date and time format. -
failed_payments_count
integer
required
The number of consecutive payment failures. Resets to0
after a successful payment. If this reaches thepayment_failure_threshold
value, the subscription updates to theSUSPENDED
state.
subscription_cancel_request
-
reason
string
required
The reason for the cancellation of a subscription.
subscription_capture_request
-
note
string
required
The reason or note for the subscription charge. -
capture_type
enum
required
The type of capture. The possible values are:OUTSTANDING_BALANCE
. The outstanding balance that the subscriber must clear.
-
The amount of the outstanding balance. This value cannot be greater than the current outstanding balance amount.
subscription_collection
-
subscriptions
array (contains the subscription object)
An array of subscriptions. -
total_items
integer
The total number of items. -
total_pages
integer
The total number of pages. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
subscription_request
-
plan_id
string
required
The ID of the plan. -
start_time
The date and time when the subscription started, in Internet date and time format. -
quantity
string
The quantity of the product in the subscription. -
shipping_amount
The shipping charges. -
subscriber
The subscriber information. -
auto_renewal
boolean
DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete. -
application_context
The application context, which customizes the payer experience during the subscription approval process with PayPal.
subscription_revise_request
-
plan_id
string
The unique PayPal-generated ID for the plan. -
quantity
string
The quantity of the product or service in the subscription. -
effective_time
The date and time when this change is effective, in Internet date and time format. Defaults to the current time. -
shipping_amount
The shipping charges. -
shipping_address
The shipping address of the subscriber.
subscription_revise_request
-
plan_id
string
The unique PayPal-generated ID for the plan. -
quantity
string
The quantity of the product or service in the subscription. -
effective_time
The date and time when this change is effective, in Internet date and time format. Defaults to the current time. -
shipping_amount
The shipping charges. -
shipping_address
The shipping address of the subscriber.
-
links
array (contains the link_description object)
An array of request-related HATEOAS links.
subscription_revise_request
-
plan_id
string
The unique PayPal-generated ID for the plan. -
quantity
string
The quantity of the product or service in the subscription. -
effective_time
The date and time when this change is effective, in Internet date and time format. Defaults to the current time. -
shipping_amount
The shipping charges. -
shipping_address
The shipping address of the subscriber. -
application_context
The application context, which customizes the payer experience during the subscription approval process with PayPal.
subscription_revise_request.application_context
-
brand_name
string
The label that overrides the business name in the PayPal account on the PayPal site. -
locale
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
, orzh-TW
. -
shipping_preference
enum
The location from which the shipping address is derived. The possible values are: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.
-
payment_method
The customer and merchant payment preferences. Currently only PAYPAL payment method is supported. -
return_url
string
required
The URL where the customer is redirected after the customer approves the payment. -
cancel_url
string
required
The URL where the customer is redirected after the customer cancels the payment.
subscription_save_request
-
token_id
string
required
The identifier of session for which subscription needs to be saved.
subscription_status
-
status
enum
The status of the subscription. The possible values are: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
The reason or notes for the status of the subscription. -
status_update_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.
subscription_suspend_request
-
reason
string
required
The reason for suspenson of the subscription.
tax_info
-
tax_id
string
required
The customer's tax ID. Supported for the PayPal payment method only. Typically, the tax ID is 11 characters long for individuals and 14 characters long for businesses. -
tax_id_type
enum
required
The customer's tax ID type. Supported for the PayPal payment method only. The possible values are:BR_CPF
. The individual tax ID type.BR_CNPJ
. The business tax ID type.
taxes
-
The tax percentage on the billing amount.
-
inclusive
boolean
Indicates whether the tax was already included in the billing amount.
transaction
-
status
enum
The status of the captured payment. The possible values are: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, seestatus.details
REFUNDED
. An amount greater than or equal to this captured payment's amount was refunded to the payer.
-
id
string
The PayPal-generated transaction ID. -
amount_with_breakdown
The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts. -
payer_name
The name of the customer. -
payer_email
The email ID of the customer. -
time
The date and time when the transaction was processed, in Internet date and time format.
transactions_list
-
transactions
array (contains the transaction object)
An array of transactions. -
total_items
integer
The total number of items. -
total_pages
integer
The total number of pages. -
links
array (contains the link_description object)
An array of request-related HATEOAS links.
update_pricing_scheme_request
-
billing_cycle_sequence
integer
required
The billing cycle sequence. -
The pricing scheme details.
update_pricing_schemes_list_request
-
An array of pricing schemes.