Subscriptions API

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.

Plans (resource group)

Use the /billing/plans resource to create and manage plans.

Create plan

POST /v1/billing/plans

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

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.
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 the id, status and HATEOAS links.
- return=representation. The server returns a complete resource representation, including the current state of the resource.
Default: return=minimal.
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.

Minimum length: 6.

Maximum length: 50.
name

string

required

The plan name.

Minimum length: 1.

Maximum length: 127.
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.
Default: ACTIVE.

Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
description

string

The detailed description of the plan.

Minimum length: 1.

Maximum length: 127.
billing_cycles

array (contains the billing_cycle object)

required

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

object

required

The payment preferences for a subscription.
taxes

object

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

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

id

string

The unique PayPal-generated ID for the plan.

Read only.

Minimum length: 3.

Maximum length: 50.
product_id

string

The ID for the product.

Minimum length: 6.

Maximum length: 50.
name

string

The plan name.

Minimum length: 1.

Maximum length: 127.
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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
description

string

The detailed description of the plan.

Minimum length: 1.

Maximum length: 127.
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

object

The payment preferences for a subscription.
taxes

object

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

string

The date and time when the plan was created, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
update_time

string

The date and time when the plan was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

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

GET /v1/billing/plans

Lists billing plans.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.
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 the id, name, description and HATEOAS links.
- return=representation. The server returns a complete resource representation, including the current state of the resource.
Default: return=minimal.

Query parameters

product_id

string

Filters the response by a Product ID.

Minimum length: 6.

Maximum length: 50.
plan_ids

string

Filters the response by list of plan IDs. Filter supports upto 10 plan IDs.

Minimum value: 3.

Maximum value: 270.
page_size

integer

The number of items to return in the response.

Default: 10.

Minimum value: 1.

Maximum value: 20.
page

integer

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.

Default: 1.

Minimum value: 1.

Maximum value: 100000.
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

A successful request returns the HTTP 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.

Minimum value: 0.

Maximum value: 500000000.
total_pages

integer

The total number of pages.

Minimum value: 0.

Maximum value: 100000000.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

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

PATCH /v1/billing/plans/{plan_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 object	Operations
`description`	replace
`payment_preferences.auto_bill_outstanding`	replace
`taxes.percentage`	replace
`payment_preferences.payment_failure_threshold`	replace

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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

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

Sample Response

204 No Content

Show plan details

GET /v1/billing/plans/{plan_id}

Shows details for a plan, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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

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

id

string

The unique PayPal-generated ID for the plan.

Read only.

Minimum length: 3.

Maximum length: 50.
product_id

string

The ID for the product.

Minimum length: 6.

Maximum length: 50.
name

string

The plan name.

Minimum length: 1.

Maximum length: 127.
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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
description

string

The detailed description of the plan.

Minimum length: 1.

Maximum length: 127.
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

object

The payment preferences for a subscription.
taxes

object

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

string

The date and time when the plan was created, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
update_time

string

The date and time when the plan was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

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

POST /v1/billing/plans/{plan_id}/activate

Activates a plan, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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

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

Sample Response

204 No Content

Deactivate plan

POST /v1/billing/plans/{plan_id}/deactivate

Deactivates a plan, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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

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

Sample Response

204 No Content

Update pricing

POST /v1/billing/plans/{plan_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.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

Path parameters

plan_id

string

required

The ID for the plan.

Request body

pricing_schemes

array (contains the update_pricing_scheme_request object)

required

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

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

Sample Response

204 No Content

Subscriptions (resource group)

Use the /billing/subscriptions resource to create and manage subscriptions.

Create subscription

POST /v1/billing/subscriptions

Creates a subscription.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.
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 the id, status and HATEOAS links.
- return=representation. The server returns a complete resource representation, including the current state of the resource.
Default: return=minimal.
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.

Minimum length: 3.

Maximum length: 50.
start_time

string

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

Default: Current time.
quantity

string

The quantity of the product in the subscription.

Minimum length: 1.

Maximum length: 32.

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

object

The shipping charges.
subscriber

object

The subscriber information.
auto_renewal

boolean

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

object

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

A successful request returns the HTTP 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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
status_change_note

string

The reason or notes for the status of the subscription.

Minimum length: 1.

Maximum length: 128.
status_update_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.

Read only.
id

string

The PayPal-generated ID for the subscription.

Read only.

Minimum length: 3.

Maximum length: 50.
plan_id

string

The ID of the plan.

Minimum length: 3.

Maximum length: 50.
start_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.
quantity

string

The quantity of the product in the subscription.

Minimum length: 1.

Maximum length: 32.

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

object

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

object

The subscriber information.
billing_info

object

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

Read only.
create_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.

Read only.
update_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.

Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

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

PATCH /v1/billing/subscriptions/{subscription_id}

Updates a subscription, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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

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

Sample Response

204 No Content

Show subscription details

GET /v1/billing/subscriptions/{subscription_id}

Shows details for a subscription, by ID.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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

A successful request returns the HTTP 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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
status_change_note

string

The reason or notes for the status of the subscription.

Minimum length: 1.

Maximum length: 128.
status_update_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.

Read only.
id

string

The PayPal-generated ID for the subscription.

Read only.

Minimum length: 3.

Maximum length: 50.
plan_id

string

The ID of the plan.

Minimum length: 3.

Maximum length: 50.
start_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.
quantity

string

The quantity of the product in the subscription.

Minimum length: 1.

Maximum length: 32.

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

object

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

object

The subscriber information.
billing_info

object

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

Read only.
create_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.

Read only.
update_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.

Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

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

POST /v1/billing/subscriptions/{subscription_id}/activate

Activates the subscription.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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.

Minimum length: 1.

Maximum length: 128.

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

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

Sample Response

204 No Content

Cancel subscription

POST /v1/billing/subscriptions/{subscription_id}/cancel

Cancels the subscription.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

Path parameters

subscription_id

string

required

The ID of the subscription.

Request body

reason

string

required

The reason for the cancellation of a subscription.

Minimum length: 1.

Maximum length: 128.

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

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

Sample Response

204 No Content

Capture authorized payment on subscription

POST /v1/billing/subscriptions/{subscription_id}/capture

Captures an authorized payment from the subscriber on the subscription.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.
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.

Minimum length: 1.

Maximum length: 128.
capture_type

enum

required
The type of capture. The allowed values are:
- OUTSTANDING_BALANCE. The outstanding balance that the subscriber must clear.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
amount

object

required

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

Request Accepted.

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, see status.details
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.
id

string

The PayPal-generated transaction ID.

Read only.

Minimum length: 3.

Maximum length: 50.
amount_with_breakdown

object

The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.
payer_name

object

The name of the customer.

Read only.
payer_email

string

The email ID of the customer.

Read only.

Minimum length: 3.

Maximum length: 254.

Pattern: ^.+@[^"\-].+$.
time

string

The date and time when the transaction was processed, in Internet date and time format.

Read only.

Sample Response

202 Accepted

Update quantity of product or service in subscription

POST /v1/billing/subscriptions/{subscription_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.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

Path parameters

subscription_id

string

required

The ID of the subscription.

Request body

plan_id

string

The unique PayPal-generated ID for the plan.

Minimum length: 3.

Maximum length: 50.
quantity

string

The quantity of the product or service in the subscription.

Minimum length: 1.

Maximum length: 32.

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

object

The shipping charges.
shipping_address

object

The shipping address of the subscriber.
application_context

object

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

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

plan_id

string

The unique PayPal-generated ID for the plan.

Minimum length: 3.

Maximum length: 50.
quantity

string

The quantity of the product or service in the subscription.

Minimum length: 1.

Maximum length: 32.

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

string

The date and time when this change is effective, in Internet date and time format. Defaults to the current time.

Read only.
shipping_amount

object

The shipping charges.
shipping_address

object

The shipping address of the subscriber.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

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

POST /v1/billing/subscriptions/{subscription_id}/suspend

Suspends the subscription.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

Path parameters

subscription_id

string

required

The ID of the subscription.

Request body

reason

string

required

The reason for suspenson of the subscription.

Minimum length: 1.

Maximum length: 128.

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

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

Sample Response

204 No Content

List transactions for subscription

GET /v1/billing/subscriptions/{subscription_id}/transactions

Lists transactions for a subscription.

Header parameters

For more information about HTTP request headers, see HTTP request headers.

Authorization

string

required

To make REST API calls, include the bearer token in the Authorization header with the Bearer authentication scheme. The value is Bearer <Access-Token> or Basic <client_id>:<secret>.
Content-Type

string

required

The media type. Required for operations with a request body. The value is application/<format>, where the format is json.

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.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
end_time

string

required

The end time of the range of transactions to list.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

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

A successful request returns the HTTP 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.

Minimum value: 0.

Maximum value: 500000000.
total_pages

integer

The total number of pages.

Minimum value: 0.

Maximum value: 100000000.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

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.

Maximum length: 100.
street_name

string

The street name. Just Drury in Drury Lane.

Maximum length: 100.
street_type

string

The street type. For example, avenue, boulevard, road, or expressway.

Maximum length: 100.
delivery_service

string

The delivery service. Post office box, bag number, or post office name.

Maximum length: 100.
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.

Maximum length: 100.
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.

Maximum length: 100.

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.

Maximum length: 300.
address_line_2

string

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

Maximum length: 300.
address_line_3

string

The third line of the address, if needed. For example, a street complement for Brazil, direction text, such as next to Walmart, or a landmark in an Indian address.

Maximum length: 100.
admin_area_4

string
The neighborhood, ward, or district. Smaller than admin_area_level_3 or sub_locality. Value is:
- The postal sorting code for Guernsey and many French territories, such as French Guiana.
- The fine-grained administrative levels in China.
Maximum length: 100.
admin_area_3

string
A sub-locality, suburb, neighborhood, or district. Smaller than admin_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.
Maximum length: 100.
admin_area_2

string

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

Maximum length: 120.
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 not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
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.

Maximum length: 60.
country_code

string

required

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.

Minimum length: 2.

Maximum length: 2.

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

object

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 of address_details.street_number, street_name, and street_type.

address_portable_postal_code_validation

address_portable_postal_code_validation

amount_with_breakdown

gross_amount

object

required

The amount for this transaction.

Read only.
fee_amount

object

The fee details for the transaction.

Read only.
shipping_amount

object

The shipping amount for the transaction.

Read only.
tax_amount

object

The tax amount for the transaction.

Read only.
net_amount

object

required

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.

Read only.

application_context

brand_name

string

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

Minimum length: 1.

Maximum length: 127.
locale

string

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.

Minimum length: 2.

Maximum length: 10.

Pattern: ^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$.
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.
Default: GET_FROM_FILE.

Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
user_action

enum
Configures the label name to Continue or Subscribe 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.
Default: SUBSCRIBE_NOW.

Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
payment_method

object

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.

Minimum length: 10.

Maximum length: 4000.
cancel_url

string

required

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

Minimum length: 10.

Maximum length: 4000.

billing_cycle

pricing_scheme

object

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

object

required

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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
sequence

integer

required

The order in which this cycle is to run among other billing cycles. For example, a trial billing cycle has a sequence of 1 while a regular billing cycle has a sequence of 2, so that trial cycle runs before the regular cycle.

Minimum value: 1.

Maximum value: 99.
total_cycles

integer

The number of times this billing cycle runs. Trial billing cycles can only have a value of 1 for total_cycles. Regular billing cycles can either have infinite cycles (value of 0 for total_cycles) or a finite number of cycles (value between 1 and 999 for total_cycles).

Default: 1.

Minimum value: 0.

Maximum value: 999.

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, see status.details
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.

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, see status.details
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.
status_details

object

The details of the captured payment status.

Read only.

capture_status_details

reason

enum
The reason why the captured payment status is PENDING or DENIED. 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 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.

Minimum length: 2.

Maximum length: 2.

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

currency_code

currency_code

string

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

Minimum length: 3.

Maximum length: 3.

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.
Read only.

Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
sequence

integer

required

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

Minimum value: 0.

Maximum value: 99.
cycles_completed

integer

required

The number of billing cycles that have completed.

Read only.

Minimum value: 0.

Maximum value: 9999.
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.

Read only.

Minimum value: 0.

Maximum value: 9999.
current_pricing_scheme_version

integer

The active pricing scheme version for the billing cycle.

Read only.

Minimum value: 1.

Maximum value: 99.
total_cycles

integer

The number of times this billing cycle runs. Trial billing cycles can only have a value of 1 for total_cycles. Regular billing cycles can either have infinite cycles (value of 0 for total_cycles) or a finite number of cycles (value between 1 and 999 for total_cycles).

Read only.

Minimum value: 0.

Maximum value: 999.

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

Minimum length: 10.

Maximum length: 10.

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

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.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

email

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.

Maximum length: 254.

Pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).

email_address

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.

Minimum length: 3.

Maximum length: 254.

Pattern: ^.+@[^"\-].+$.

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.

Read only.
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.

Read only.

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 is body, path, or query.

Default: body.
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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
interval_count

integer

The number of intervals after which a subscriber is billed. For example, if the interval_unit is DAY with an interval_count of 2, the subscription is billed once every two days. The following table lists the maximum allowed values for the interval_count for each interval_unit:
Interval unit Maximum interval count
DAY 365
WEEK 52
MONTH 12
YEAR 1

Default: 1.

Minimum value: 1.

Maximum value: 365.

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

Minimum length: 2.

Maximum length: 10.

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

last_payment_details

amount

object

required

The last payment amount.

Read only.
time

string

required

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

Read only.

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. The href 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.

Possible values: GET, POST, PUT, DELETE, HEAD, CONNECT, OPTIONS, PATCH.

money

currency_code

string

required

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

Minimum length: 3.

Maximum length: 3.
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.
For the required number of decimal places for a currency code, see Currency Codes.
Maximum length: 32.

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

name

prefix

string

The prefix, or title, to the party's name.

Maximum length: 140.
given_name

string

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

Maximum length: 140.
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.

Maximum length: 140.
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.

Maximum length: 140.
suffix

string

The suffix for the party's name.

Maximum length: 140.
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.

Maximum length: 300.
full_name

string

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

Maximum length: 300.

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

Type	Considered equal if both values
strings	Contain the same number of Unicode characters and their code points are byte-by-byte equal.
numbers	Are numerically equal.
arrays	Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
objects	Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
literals (`false`, `true`, and `null`)	Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.

For more information, see 4.6. test.

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

patch_request

patch_request

array (contains the patch object)

An array of JSON patch objects to apply partial updates to resources.

payer

name

object

The name of the payer. Supports only the given_name and surname properties.
email_address

string

The email address of the payer.

Maximum length: 254.

Pattern: (?:[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*|(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21\x23-\x5b\x5d-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])*")@(?:(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?|\[(?:(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9]))\.){3}(?:(2(5[0-5]|[0-4][0-9])|1[0-9][0-9]|[1-9]?[0-9])|[a-zA-Z0-9-]*[a-zA-Z0-9]:(?:[\x01-\x08\x0b\x0c\x0e-\x1f\x21-\x5a\x53-\x7f]|\[\x01-\x09\x0b\x0c\x0e-\x7f])+)\]).
payer_id

string

The PayPal assigned ID for the payer.

Read only.

Minimum length: 13.

Maximum length: 13.

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

object

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

string

The birth date of the payer in YYYY-MM-DD format.

Minimum length: 10.

Maximum length: 10.

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

object

The tax information of the payer. Required only for Brazilian payer's. Both tax_id and tax_id_type are required.
address

object

The address of the payer. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties. Also referred to as the billing address of the customer.

payer

name

object

The name of the payer. Supports only the given_name and surname properties.
email_address

string

The email address of the payer.

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.

Maximum length: 300.
address_line_2

string

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

Maximum length: 300.
admin_area_2

string

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

Maximum length: 120.
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 not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
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.

Maximum length: 60.
country_code

string

required

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.

payer.name

given_name

string

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

Maximum length: 140.
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.

Maximum length: 140.

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.

Minimum length: 13.

Maximum length: 13.

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

payment_method

payer_selected

string

The customer-selected payment method on the merchant site.

Default: PAYPAL.

Minimum length: 1.

Pattern: ^[0-9A-Z_]+$.
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.
Default: UNRESTRICTED.

Minimum length: 1.

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

payment_preferences

auto_bill_outstanding

boolean

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

Default: true.
setup_fee

object

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.
Default: CANCEL.

Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
payment_failure_threshold

integer

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.

Default: 0.

Minimum value: 0.

Maximum value: 999.

percentage

percentage

string

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

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

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

Minimum length: 1.

Maximum length: 3.

Pattern: ^[0-9]{1,3}?$.
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).

Minimum length: 1.

Maximum length: 14.

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

string

The extension number.

Minimum length: 1.

Maximum length: 15.

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

phone_type

phone_type

enum

The phone type.

Possible values: FAX, HOME, MOBILE, OTHER, PAGER.

phone_with_type

phone_type

enum

The phone type.

Possible values: FAX, HOME, MOBILE, OTHER, PAGER.
phone_number

object

required

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

Minimum length: 1.

Maximum length: 14.

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

plan

id

string

The unique PayPal-generated ID for the plan.

Read only.

Minimum length: 3.

Maximum length: 50.
product_id

string

The ID for the product.

Minimum length: 6.

Maximum length: 50.
name

string

The plan name.

Minimum length: 1.

Maximum length: 127.
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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
description

string

The detailed description of the plan.

Minimum length: 1.

Maximum length: 127.
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

object

The payment preferences for a subscription.
taxes

object

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

string

The date and time when the plan was created, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
update_time

string

The date and time when the plan was last updated, in Internet date and time format.

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

plan_collection

plans

array (contains the plan object)

An array of plans.
total_items

integer

The total number of items.

Minimum value: 0.

Maximum value: 500000000.
total_pages

integer

The total number of pages.

Minimum value: 0.

Maximum value: 100000000.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

plan_request

product_id

string

required

The ID of the product.

Minimum length: 6.

Maximum length: 50.
name

string

required

The plan name.

Minimum length: 1.

Maximum length: 127.
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.
Default: ACTIVE.

Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
description

string

The detailed description of the plan.

Minimum length: 1.

Maximum length: 127.
billing_cycles

array (contains the billing_cycle object)

required

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

object

required

The payment preferences for a subscription.
taxes

object

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.

Read only.

Minimum value: 0.

Maximum value: 999.
fixed_price

object

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

string

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

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.
update_time

string

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

Read only.

Minimum length: 20.

Maximum length: 64.

Pattern: ^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])[T,t]([0-1][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]+)?([Zz]|[+-][0-9]{2}:[0-9]{2})$.

shipping_detail

name

object

The name of the person to whom to ship the items. Supports only the full_name property.
address

object

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.

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.

Maximum length: 300.
address_line_2

string

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

Maximum length: 300.
admin_area_2

string

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

Maximum length: 120.
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 not California. Value, by country, is:
- UK. A county.
- US. A state.
- Canada. A province.
- Japan. A prefecture.
- Switzerland. A kanton.
Maximum length: 300.
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.

Maximum length: 60.
country_code

string

required

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.

shipping_detail.name

full_name

string

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

Maximum length: 300.

subscriber

name

object

The name of the payer. Supports only the given_name and surname properties.
email_address

string

The email address of the payer.

shipping_address

object

The shipping details.

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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
status_change_note

string

The reason or notes for the status of the subscription.

Minimum length: 1.

Maximum length: 128.
status_update_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.

Read only.

id

string

The PayPal-generated ID for the subscription.

Read only.

Minimum length: 3.

Maximum length: 50.
plan_id

string

The ID of the plan.

Minimum length: 3.

Maximum length: 50.
start_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.
quantity

string

The quantity of the product in the subscription.

Minimum length: 1.

Maximum length: 32.

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

object

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

object

The subscriber information.
billing_info

object

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

Read only.
create_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.

Read only.
update_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.

Read only.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

subscription_activate_request

reason

string

The reason for activation of a subscription. Required to reactivate the subscription.

Minimum length: 1.

Maximum length: 128.

subscription_billing_info

outstanding_balance

object

required

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.

Read only.
last_payment

object

The details for the last payment of the subscription.

Read only.
next_billing_time

string

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

Read only.
final_payment_time

string

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

Read only.
failed_payments_count

integer

required

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.

Read only.

Minimum value: 0.

Maximum value: 999.

subscription_cancel_request

reason

string

required

The reason for the cancellation of a subscription.

Minimum length: 1.

Maximum length: 128.

subscription_capture_request

note

string

required

The reason or note for the subscription charge.

Minimum length: 1.

Maximum length: 128.
capture_type

enum

required
The type of capture. The possible values are:
- OUTSTANDING_BALANCE. The outstanding balance that the subscriber must clear.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
amount

object

required

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.

Minimum value: 0.

Maximum value: 500000000.
total_pages

integer

The total number of pages.

Minimum value: 0.

Maximum value: 100000000.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

subscription_request

plan_id

string

required

The ID of the plan.

Minimum length: 3.

Maximum length: 50.
start_time

string

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

Default: Current time.
quantity

string

The quantity of the product in the subscription.

Minimum length: 1.

Maximum length: 32.

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

object

The shipping charges.
subscriber

object

The subscriber information.
auto_renewal

boolean

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

object

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.

Minimum length: 3.

Maximum length: 50.
quantity

string

The quantity of the product or service in the subscription.

Minimum length: 1.

Maximum length: 32.

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

string

The date and time when this change is effective, in Internet date and time format. Defaults to the current time.

Read only.
shipping_amount

object

The shipping charges.
shipping_address

object

The shipping address of the subscriber.

subscription_revise_request

plan_id

string

The unique PayPal-generated ID for the plan.

Minimum length: 3.

Maximum length: 50.
quantity

string

The quantity of the product or service in the subscription.

Minimum length: 1.

Maximum length: 32.

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

string

The date and time when this change is effective, in Internet date and time format. Defaults to the current time.

Read only.
shipping_amount

object

The shipping charges.
shipping_address

object

The shipping address of the subscriber.

links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

subscription_revise_request

plan_id

string

The unique PayPal-generated ID for the plan.

Minimum length: 3.

Maximum length: 50.
quantity

string

The quantity of the product or service in the subscription.

Minimum length: 1.

Maximum length: 32.

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

string

The date and time when this change is effective, in Internet date and time format. Defaults to the current time.

Read only.
shipping_amount

object

The shipping charges.
shipping_address

object

The shipping address of the subscriber.
application_context

object

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.

Minimum length: 1.

Maximum length: 127.
locale

string

The BCP 47-formatted locale of pages that the PayPal payment experience shows. PayPal supports a five-character code. For example, da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, or zh-TW.
shipping_preference

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.
Default: GET_FROM_FILE.

Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
payment_method

object

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.

Minimum length: 10.

Maximum length: 4000.
cancel_url

string

required

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

Minimum length: 10.

Maximum length: 4000.

subscription_save_request

token_id

string

required

The identifier of session for which subscription needs to be saved.

Minimum length: 3.

Maximum length: 50.

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.
Minimum length: 1.

Maximum length: 24.

Pattern: ^[A-Z_]+$.
status_change_note

string

The reason or notes for the status of the subscription.

Minimum length: 1.

Maximum length: 128.
status_update_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.

Read only.

subscription_suspend_request

reason

string

required

The reason for suspenson of the subscription.

Minimum length: 1.

Maximum length: 128.

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.

Maximum length: 14.
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

percentage

string

required

The tax percentage on the billing amount.

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

boolean

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

Default: true.

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, see status.details
- REFUNDED. An amount greater than or equal to this captured payment's amount was refunded to the payer.
Read only.

id

string

The PayPal-generated transaction ID.

Read only.

Minimum length: 3.

Maximum length: 50.
amount_with_breakdown

object

The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.
payer_name

object

The name of the customer.

Read only.
payer_email

string

The email ID of the customer.

Read only.

Minimum length: 3.

Maximum length: 254.

Pattern: ^.+@[^"\-].+$.
time

string

The date and time when the transaction was processed, in Internet date and time format.

Read only.

transactions_list

transactions

array (contains the transaction object)

An array of transactions.
total_items

integer

The total number of items.

Minimum value: 0.

Maximum value: 500000000.
total_pages

integer

The total number of pages.

Minimum value: 0.

Maximum value: 100000000.
links

array (contains the link_description object)

An array of request-related HATEOAS links.

Read only.

update_pricing_scheme_request

billing_cycle_sequence

integer

required

The billing cycle sequence.

Minimum value: 1.

Maximum value: 99.
pricing_scheme

object

required

The pricing scheme details.

update_pricing_schemes_list_request

pricing_schemes

array (contains the update_pricing_scheme_request object)

required

An array of pricing schemes.

Authorization

Content-Type

Prefer

PayPal-Request-Id

product_id

name

status

description

billing_cycles

payment_preferences

taxes

quantity_supported

Sample Request

id

product_id

name

status

description

billing_cycles

payment_preferences

taxes

quantity_supported

create_time

update_time

links

Sample Response

Authorization

Content-Type

Prefer

product_id

plan_ids

page_size

page

total_required

Sample Request

plans

total_items

total_pages

links

Sample Response

Authorization

Content-Type

plan_id

patch_request

Sample Request

Sample Response

Authorization

Content-Type

plan_id

Sample Request

id

product_id

name

status

description

billing_cycles

payment_preferences

taxes

quantity_supported

create_time

update_time

links

Sample Response

Authorization

Content-Type

plan_id

Sample Request

Sample Response

Authorization

Content-Type

plan_id

Sample Request

Sample Response

Authorization

Content-Type

plan_id

pricing_schemes

Sample Request

Sample Response

Authorization

`Authorization`

`Content-Type`

`Prefer`

`PayPal-Request-Id`

`product_id`

`name`

`status`

`description`

`billing_cycles`

`payment_preferences`

`taxes`

`quantity_supported`

`id`

`product_id`

`name`

`status`

`description`

`billing_cycles`

`payment_preferences`

`taxes`

`quantity_supported`

`create_time`

`update_time`

`links`

`Authorization`

`Content-Type`

`Prefer`

`product_id`

`plan_ids`

`page_size`

`page`

`total_required`

`plans`

`total_items`

`total_pages`

`links`

`Authorization`

`Content-Type`

`plan_id`

`patch_request`

`Authorization`

`Content-Type`

`plan_id`

`id`

`product_id`

`name`

`status`

`description`

`billing_cycles`

`payment_preferences`

`taxes`

`quantity_supported`

`create_time`

`update_time`

`links`

`Authorization`

`Content-Type`

`plan_id`

`Authorization`

`Content-Type`

`plan_id`

`Authorization`

`Content-Type`

`plan_id`

`pricing_schemes`

`Authorization`

`Content-Type`

`Prefer`

`PayPal-Request-Id`

`plan_id`

`start_time`

`quantity`

`shipping_amount`

`subscriber`

`auto_renewal`

`application_context`

`status`

`status_change_note`

`status_update_time`

`id`