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.

List plans

GET/v1/billing/plans
Lists billing plans.

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.

    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.

    Minimum value: 1.

    Maximum value: 100000.

  • total_required

    boolean

    Indicates whether to show the total count in the response.

Header parameters

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

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.

    Maximum value: 500000000.

  • total_pages

    integer

    The total number of pages.

    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"
    }
  ]
}

Create plan

POST/v1/billing/plans
Creates a plan that defines pricing and billing cycle details for subscriptions.

Header parameters

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

  • PayPal-Request-Id

    string

    The server stores keys for 72 hours.

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

    required

    An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle.

  • 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": 2,
      "pricing_scheme": {
        "fixed_price": {
          "value": "3",
          "currency_code": "USD"
        }
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 2,
      "total_cycles": 3,
      "pricing_scheme": {
        "fixed_price": {
          "value": "6",
          "currency_code": "USD"
        }
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 3,
      "total_cycles": 12,
      "pricing_scheme": {
        "fixed_price": {
          "value": "10",
          "currency_code": "USD"
        }
      }
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "value": "10",
      "currency_code": "USD"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10",
    "inclusive": false
  }
}'

Response

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 billing and regular billing. A plan can have at most two trial cycles and only one regular 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": 2,
      "pricing_scheme": {
        "fixed_price": {
          "value": "3",
          "currency_code": "USD"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "TRIAL",
      "sequence": 2,
      "total_cycles": 3,
      "pricing_scheme": {
        "fixed_price": {
          "currency_code": "USD",
          "value": "6"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    },
    {
      "frequency": {
        "interval_unit": "MONTH",
        "interval_count": 1
      },
      "tenure_type": "REGULAR",
      "sequence": 3,
      "total_cycles": 12,
      "pricing_scheme": {
        "fixed_price": {
          "currency_code": "USD",
          "value": "10"
        },
        "version": 1,
        "create_time": "2020-05-27T12:13:51Z",
        "update_time": "2020-05-27T12:13:51Z"
      }
    }
  ],
  "payment_preferences": {
    "auto_bill_outstanding": true,
    "setup_fee": {
      "value": "10",
      "currency_code": "USD"
    },
    "setup_fee_failure_action": "CONTINUE",
    "payment_failure_threshold": 3
  },
  "taxes": {
    "percentage": "10",
    "inclusive": false
  },
  "create_time": "2020-05-27T12:13:51Z",
  "update_time": "2020-05-27T12:13:51Z",
  "links": [
    {
      "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"
    }
  ]
}

Update plan

PATCH/v1/billing/plans/{id}
Updates a plan with the `CREATED` or `ACTIVE` status. For an `INACTIVE` plan, you can make only status updates.
You can patch these attributes and objects:
Attribute or objectOperations
descriptionreplace
payment_preferences.auto_bill_outstandingreplace
taxes.percentagereplace
payment_preferences.payment_failure_thresholdreplace
payment_preferences.setup_feereplace
payment_preferences.setup_fee_failure_actionreplace

Header parameters

  • 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

  • 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/{id}
    Shows details for a plan, by ID.

    Header parameters

    • 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

    • 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 billing and regular billing. A plan can have at most two trial cycles and only one regular 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": 2,
          "pricing_scheme": {
            "fixed_price": {
              "currency_code": "USD",
              "value": "3"
            },
            "version": 1,
            "create_time": "2020-05-27T12:13:51Z",
            "update_time": "2020-05-27T12:13:51Z"
          }
        },
        {
          "frequency": {
            "interval_unit": "MONTH",
            "interval_count": 1
          },
          "tenure_type": "TRIAL",
          "sequence": 2,
          "total_cycles": 3,
          "pricing_scheme": {
            "fixed_price": {
              "currency_code": "USD",
              "value": "6"
            },
            "version": 1,
            "create_time": "2020-05-27T12:13:51Z",
            "update_time": "2020-05-27T12:13:51Z"
          }
        },
        {
          "frequency": {
            "interval_unit": "MONTH",
            "interval_count": 1
          },
          "tenure_type": "REGULAR",
          "sequence": 3,
          "total_cycles": 12,
          "pricing_scheme": {
            "fixed_price": {
              "value": "10",
              "currency_code": "USD"
            },
            "status": "ACTIVE",
            "version": 1,
            "create_time": "2020-05-27T12:13:51Z",
            "update_time": "2020-05-27T12:13:51Z"
          }
        }
      ],
      "taxes": {
        "percentage": "10",
        "inclusive": false
      },
      "create_time": "2020-05-27T12:13:51Z",
      "update_time": "2020-05-27T12:13:51Z",
      "links": [
        {
          "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/{id}/activate
    Activates a plan, by ID.

    Header parameters

    • 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

    • 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/{id}/deactivate
      Deactivates a plan, by ID.

      Header parameters

      • 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

      • 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/{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

        • 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

        • id

          string

          required

          The ID for the plan.

        Request body

        Sample Request

        curl -v -X POST https://api.sandbox.paypal.com/v1/billing/plans/P-7GL4271244454362WXNWU5NQ/update-pricing-schemes \
        -H "Content-Type: application/json" \
        -H "Authorization: Bearer Access-Token" \
        -d '{
          "pricing_schemes": [
            {
              "billing_cycle_sequence": 1,
              "pricing_scheme": {
                "fixed_price": {
                  "value": "50",
                  "currency_code": "USD"
                },
                "roll_out_strategy": {
                  "effective_time": "2019-02-10T21:20:49Z",
                  "process_change_from": "NEXT_PAYMENT"
                }
              }
            },
            {
              "billing_cycle_sequence": 2,
              "pricing_scheme": {
                "fixed_price": {
                  "value": "100",
                  "currency_code": "USD"
                },
                "pricing_model": "VOLUME",
                "tiers": [
                  {
                    "starting_quantity": "1",
                    "ending_quantity": "1000",
                    "amount": {
                      "value": "150",
                      "currency_code": "USD"
                    }
                  },
                  {
                    "starting_quantity": "1001",
                    "amount": {
                      "value": "250",
                      "currency_code": "USD"
                    }
                  }
                ],
                "roll_out_strategy": {
                  "effective_time": "2019-02-10T21:20:49Z",
                  "process_change_from": "NEXT_PAYMENT"
                }
              }
            }
          ]
        }'

        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

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

          • PayPal-Request-Id

            string

            The server stores keys for 72 hours.

          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.

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

          • custom_id

            string

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

            Minimum length: 1.

            Maximum length: 127.

            Pattern: ^[\x20-\x7E]+.

          • plan

            object

            An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object.

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

          • custom_id

            string

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

            Minimum length: 1.

            Maximum length: 127.

            Pattern: ^[\x20-\x7E]+.

          • plan_overridden

            boolean

            Indicates whether the subscription has overridden any plan attributes.

            Read only.

          • plan

            object

            Inline plan details.

          • 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",
            "plan_overridden": false,
            "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",
              "payer_id": "2J6QB8YJQSJRJ",
              "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/{id}
          Updates a subscription which could be in `ACTIVE` or `SUSPENDED` status. You can override plan level default attributes by providing customised values for plan path in the patch request.
          • You cannot update attributes that have already completed (Example - trial cycles can’t be updated if completed).
          • Once overridden, changes to plan resource will not impact subscription.
          • Any price update will not impact billing cycles within next 10 days (Applicable only for subscriptions funded by PayPal account).
          Following are the fields eligible for patch.
          Attribute or objectOperations
          billing_info.outstanding_balancereplace
          custom_idadd,replace
          plan.billing_cycles[@sequence==n].
          pricing_scheme.fixed_price
          add,replace
          plan.billing_cycles[@sequence==n].
          pricing_scheme.tiers
          replace
          plan.billing_cycles[@sequence==n].
          total_cycles
          replace
          plan.payment_preferences.
          auto_bill_outstanding
          replace
          plan.payment_preferences.
          payment_failure_threshold
          replace
          plan.taxes.inclusiveadd,replace
          plan.taxes.percentageadd,replace
          shipping_amountadd,replace
          start_timereplace
          subscriber.shipping_addressadd,replace
          subscriber.payment_source
          (for subscriptions funded by card payments)
          replace

          Header parameters

          • 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

          • 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": "/plan/billing_cycles/@sequence==1/pricing_scheme/fixed_price",
              "value": {
                "currency_code": "USD",
                "value": "50.00"
              }
            },
            {
              "op": "replace",
              "path": "/plan/billing_cycles/@sequence==2/pricing_scheme/tiers",
              "value": [
                {
                  "starting_quantity": "1",
                  "ending_quantity": "1000",
                  "amount": {
                    "value": "500",
                    "currency_code": "USD"
                  }
                },
                {
                  "starting_quantity": "1001",
                  "amount": {
                    "value": "2000",
                    "currency_code": "USD"
                  }
                }
              ]
            },
            {
              "op": "replace",
              "path": "/plan/payment_preferences/auto_bill_outstanding",
              "value": true
            },
            {
              "op": "replace",
              "path": "/plan/payment_preferences/payment_failure_threshold",
              "value": 1
            },
            {
              "op": "replace",
              "path": "/plan/taxes/percentage",
              "value": "10"
            }
          ]'

          Response

          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/{id}
            Shows details for a subscription, by ID.

            Query parameters

            • fields

              string

              List of fields that are to be returned in the response. Possible value for fields are last_failed_payment and plan.

              Minimum length: 1.

              Maximum length: 100.

            Header parameters

            • 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

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

            • custom_id

              string

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

              Minimum length: 1.

              Maximum length: 127.

              Pattern: ^[\x20-\x7E]+.

            • plan_overridden

              boolean

              Indicates whether the subscription has overridden any plan attributes.

              Read only.

            • plan

              object

              Inline plan details.

            • 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",
                "payer_id": "2J6QB8YJQSJRJ"
              },
              "billing_info": {
                "outstanding_balance": {
                  "currency_code": "USD",
                  "value": "1.0"
                },
                "cycle_executions": [
                  {
                    "tenure_type": "TRIAL",
                    "sequence": 1,
                    "cycles_completed": 0,
                    "cycles_remaining": 2,
                    "total_cycles": 2
                  },
                  {
                    "tenure_type": "TRIAL",
                    "sequence": 2,
                    "cycles_completed": 0,
                    "cycles_remaining": 3,
                    "total_cycles": 3
                  },
                  {
                    "tenure_type": "REGULAR",
                    "sequence": 3,
                    "cycles_completed": 0,
                    "cycles_remaining": 12,
                    "total_cycles": 12
                  }
                ],
                "last_payment": {
                  "amount": {
                    "currency_code": "USD",
                    "value": "1.15"
                  },
                  "time": "2019-04-09T10:27:20Z"
                },
                "next_billing_time": "2019-04-10T10:00:00Z",
                "failed_payments_count": 0
              },
              "create_time": "2019-04-09T10:26:04Z",
              "update_time": "2019-04-09T10:27:27Z",
              "links": [
                {
                  "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/{id}/activate
            Activates the subscription.

            Header parameters

            • 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

            • 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/{id}/cancel
              Cancels the subscription.

              Header parameters

              • 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

              • 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/{id}/capture
                Captures an authorized payment from the subscriber on the subscription.

                Header parameters

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

                Path parameters

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

                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

                Revise plan or quantity of subscription

                POST/v1/billing/subscriptions/{id}/revise
                Updates the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the `shipping_amount`, `shipping_address` values for the subscription. This type of update requires the buyer's consent.

                Header parameters

                • 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

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

                • effective_time

                  string

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

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

                • plan

                  object

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

                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.

                • plan

                  object

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

                • plan_overridden

                  boolean

                  Indicates whether the subscription has overridden any plan attributes.

                  Read only.

                • links

                  array (contains the link_description object)

                  An array of request-related HATEOAS links.

                  Read only.

                Sample Response

                {
                  "plan_id": "P-5ML4271244454362WXNWU5NQ",
                  "plan_overridden": false,
                  "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"
                    },
                    {
                      "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/cancel",
                      "rel": "cancel",
                      "method": "POST"
                    },
                    {
                      "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"
                    }
                  ]
                }

                Suspend subscription

                POST/v1/billing/subscriptions/{id}/suspend
                Suspends the subscription.

                Header parameters

                • 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

                • 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/{id}/transactions
                  Lists transactions for a 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})$.

                  Header parameters

                  • 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

                  • id

                    string

                    required

                    The ID of the subscription.

                  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.

                    Maximum value: 500000000.

                  • total_pages

                    integer

                    The total number of pages.

                    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

                  account_id

                  • account_id

                    string

                    The account identifier for a PayPal account.

                    Minimum length: 13.

                    Maximum length: 13.

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

                  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

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

                  address_portable_postal_code_validation

                  • address_portable_postal_code_validation

                  amount_with_breakdown

                  • gross_amount

                    object

                    required

                    The amount for this transaction.

                    Read only.

                  • total_item_amount

                    object

                    The item total for the 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

                    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.

                    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.

                    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.

                  backup_funding_instrument

                  • card

                    object

                    required

                    The backup card response information.

                  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 cycle, only 2 trial cycles are 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 gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).

                    Maximum value: 999.

                  billing_cycle_override

                  • pricing_scheme

                    object

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

                  • 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 gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).

                    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.

                  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.

                  card

                  • id

                    string

                    The PayPal-generated ID for the card.

                    Read only.

                  • name

                    string

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

                    Maximum length: 300.

                  • number

                    string

                    required

                    The primary account number (PAN) for the payment card.

                    Minimum length: 13.

                    Maximum length: 19.

                  • expiry

                    string

                    required

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

                    Minimum length: 7.

                    Maximum length: 7.

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

                  • security_code

                    string

                    The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.

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

                  • last_digits

                    string

                    The last digits of the payment card.

                    Read only.

                    Pattern: [0-9]{2,}.

                  • card_type

                    enum

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

                    The possible values are:

                    • VISA. Visa card.
                    • MASTERCARD. Mastecard card.
                    • DISCOVER. Discover card.
                    • AMEX. American Express card.
                    • SOLO. Solo debit card.
                    • JCB. Japan Credit Bureau card.
                    • STAR. Military Star card.
                    • DELTA. Delta Airlines card.
                    • SWITCH. Switch credit card.
                    • MAESTRO. Maestro credit card.
                    • CB_NATIONALE. Carte Bancaire (CB) credit card.
                    • CONFIGOGA. Configoga credit card.
                    • CONFIDIS. Confidis credit card.
                    • ELECTRON. Visa Electron credit card.
                    • CETELEM. Cetelem credit card.
                    • CHINA_UNION_PAY. China union pay credit card.

                    Read only.

                  • billing_address

                    object

                    The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

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

                  card_brand

                  • card_brand

                    enum

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

                    The possible values are:

                    • VISA. Visa card.
                    • MASTERCARD. Mastecard card.
                    • DISCOVER. Discover card.
                    • AMEX. American Express card.
                    • SOLO. Solo debit card.
                    • JCB. Japan Credit Bureau card.
                    • STAR. Military Star card.
                    • DELTA. Delta Airlines card.
                    • SWITCH. Switch credit card.
                    • MAESTRO. Maestro credit card.
                    • CB_NATIONALE. Carte Bancaire (CB) credit card.
                    • CONFIGOGA. Configoga credit card.
                    • CONFIDIS. Confidis credit card.
                    • ELECTRON. Visa Electron credit card.
                    • CETELEM. Cetelem credit card.
                    • CHINA_UNION_PAY. China union pay credit card.

                    Minimum length: 1.

                    Maximum length: 255.

                    Pattern: ^[A-Z_]+$.

                  card_response

                  • last_digits

                    string

                    The last digits of the payment card.

                    Read only.

                    Pattern: [0-9]{2,}.

                  • brand

                    enum

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

                    The possible values are:

                    • VISA. Visa card.
                    • MASTERCARD. Mastecard card.
                    • DISCOVER. Discover card.
                    • AMEX. American Express card.
                    • SOLO. Solo debit card.
                    • JCB. Japan Credit Bureau card.
                    • STAR. Military Star card.
                    • DELTA. Delta Airlines card.
                    • SWITCH. Switch credit card.
                    • MAESTRO. Maestro credit card.
                    • CB_NATIONALE. Carte Bancaire (CB) credit card.
                    • CONFIGOGA. Configoga credit card.
                    • CONFIDIS. Confidis credit card.
                    • ELECTRON. Visa Electron credit card.
                    • CETELEM. Cetelem credit card.
                    • CHINA_UNION_PAY. China union pay credit card.

                    Read only.

                    Minimum length: 1.

                    Maximum length: 255.

                    Pattern: ^[A-Z_]+$.

                  • type

                    enum

                    The payment card type.

                    The possible values are:

                    • CREDIT. A credit card.
                    • DEBIT. A debit card.
                    • PREPAID. A Prepaid card.
                    • UNKNOWN. Card type cannot be determined.

                    Read only.

                  card_response_with_billing_address

                  • last_digits

                    string

                    The last digits of the payment card.

                    Pattern: [0-9]{2,}.

                  • brand

                    string

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

                    Minimum length: 1.

                    Maximum length: 255.

                    Pattern: ^[A-Z_]+$.

                  • type

                    string

                    The payment card type.

                  • name

                    string

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

                    Minimum length: 2.

                    Maximum length: 300.

                  • billing_address

                    object

                    The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

                  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

                  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.

                    Maximum value: 99.

                  • cycles_completed

                    integer

                    required

                    The number of billing cycles that have completed.

                    Read only.

                    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.

                    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 gets executed. Trial billing cycles can only be executed a finite number of times (value between 1 and 999 for total_cycles). Regular billing cycles can be executed infinite times (value of 0 for total_cycles) or a finite number of times (value between 1 and 999 for total_cycles).

                    Read only.

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

                  date_year_month

                  • date_year_month

                    string

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

                    Minimum length: 7.

                    Maximum length: 7.

                    Pattern: ^[0-9]{4}-(0[1-9]|1[0-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.

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

                  failed_payment_details

                  • amount

                    object

                    required

                    The failed payment amount.

                    Read only.

                  • time

                    string

                    required

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

                    Read only.

                  • reason_code

                    enum

                    The reason code for the payment failure.

                    The possible values are:

                    • PAYMENT_DENIED. PayPal declined the payment due to one or more customer issues.
                    • INTERNAL_SERVER_ERROR. An internal server error has occurred.
                    • PAYEE_ACCOUNT_RESTRICTED. The payee account is not in good standing and cannot receive payments.
                    • PAYER_ACCOUNT_RESTRICTED. The payer account is not in good standing and cannot make payments.
                    • PAYER_CANNOT_PAY. Payer cannot pay for this transaction.
                    • SENDING_LIMIT_EXCEEDED. The transaction exceeds the payer's sending limit.
                    • TRANSACTION_RECEIVING_LIMIT_EXCEEDED. The transaction exceeds the receiver's receiving limit.
                    • CURRENCY_MISMATCH. The transaction is declined due to a currency mismatch.

                    Read only.

                    Minimum length: 1.

                    Maximum length: 120.

                    Pattern: ^[A-Z_]+$.

                  • next_payment_retry_time

                    string

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

                    Read only.

                  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 unitMaximum interval count
                    DAY365
                    WEEK52
                    MONTH12
                    YEAR1

                    Minimum value: 1.

                    Maximum value: 365.

                  language

                  last_payment_details

                  • status

                    string

                    The status of the captured payment.

                  merchant_partner_customer_id

                  • merchant_partner_customer_id

                    string

                    The unique ID for a customer in merchant's or partner's system of records.

                    Minimum length: 1.

                    Maximum length: 22.

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

                  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:
                      TypeConsidered equal if both values
                      stringsContain the same number of Unicode characters and their code points are byte-by-byte equal.
                      numbersAre numerically equal.
                      arraysContain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.
                      objectsContain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).
                      literals (false, true, and null)Are the same. The comparison is a logical comparison. For example, whitespace between the parameter values of an array is not significant. Also, ordering of the serialization of object parameters is not significant.
                      For more information, see 4.6. test.
                  • path

                    string

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

                  • value

                    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.

                  payee_base

                  • email_address

                    string

                    The email address of merchant.

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

                  • merchant_id

                    string

                    The encrypted PayPal account ID of the merchant.

                    Minimum length: 13.

                    Maximum length: 13.

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

                  payee_payment_method_preference

                  • payee_payment_method_preference

                    enum

                    The merchant-preferred payment methods.

                    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.

                    Minimum length: 1.

                    Maximum length: 255.

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

                  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_id

                    string

                    The PayPal-assigned ID for the payer.

                    Read only.

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

                  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_id

                    string

                    The PayPal-assigned ID for the payer.

                    Read only.

                  • 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_id

                    string

                    The PayPal-assigned ID for the payer.

                    Read only.

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

                  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.

                  payment_method

                  • payer_selected

                    enum

                    The customer-selected payment method on the merchant site.

                    Minimum length: 1.

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

                  • payee_preferred

                    enum

                    The merchant-preferred payment methods.

                    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.

                    Minimum length: 1.

                    Maximum length: 255.

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

                  • standard_entry_class_code

                    enum

                    NACHA (the regulatory body governing the ACH network) requires that API callers (merchants, partners) obtain the consumer’s explicit authorization before initiating a transaction. To stay compliant, you’ll need to make sure that you retain a compliant authorization for each transaction that you originate to the ACH Network using this API. ACH transactions are categorized (using SEC codes) by how you capture authorization from the Receiver (the person whose bank account is being debited or credited). PayPal supports the following SEC codes.

                    The possible values are:

                    • TEL. The API caller (merchant/partner) accepts authorization and payment information from a consumer over the telephone.
                    • WEB. The API caller (merchant/partner) accepts Debit transactions from a consumer on their website.
                    • CCD. Cash concentration and disbursement for corporate debit transaction. Used to disburse or consolidate funds. Entries are usually Optional high-dollar, low-volume, and time-critical. (e.g. intra-company transfers or invoice payments to suppliers).
                    • PPD. Prearranged payment and deposit entries. Used for debit payments authorized by a consumer account holder, and usually initiated by a company. These are usually recurring debits (such as insurance premiums).

                    Minimum length: 3.

                    Maximum length: 255.

                  payment_preferences

                  • auto_bill_outstanding

                    boolean

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

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

                    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.

                    Maximum value: 999.

                  payment_preferences_override

                  • auto_bill_outstanding

                    boolean

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

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

                    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.

                    Maximum value: 999.

                  payment_source

                  • card

                    object

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

                  payment_source.card

                  • name

                    string

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

                    Maximum length: 300.

                  • number

                    string

                    required

                    The primary account number (PAN) for the payment card.

                    Minimum length: 13.

                    Maximum length: 19.

                  • expiry

                    string

                    required

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

                  • security_code

                    string

                    The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID.

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

                  • billing_address

                    object

                    The billing address for this card. Supports only the address_line_1, address_line_2, admin_area_1, admin_area_2, postal_code, and country_code properties.

                  payment_source_response

                  • card

                    object

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

                  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 billing and regular billing. A plan can have at most two trial cycles and only one regular 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

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

                  • 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 billing and regular billing. A plan can have at most two trial cycles and only one regular 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.

                  plan_collection

                  • plans

                    array (contains the plan object)

                    An array of plans.

                  • total_items

                    integer

                    The total number of items.

                    Maximum value: 500000000.

                  • total_pages

                    integer

                    The total number of pages.

                    Maximum value: 100000000.

                  • links

                    array (contains the link_description object)

                    An array of request-related HATEOAS links.

                    Read only.

                  plan_override

                  • billing_cycles

                    array (contains the billing_cycle_override object)

                    An array of billing cycles for trial billing and regular billing. The subscription billing cycle definition has to adhere to the plan billing cycle definition.

                  • payment_preferences

                    object

                    The payment preferences to override at subscription level.

                  • taxes

                    object

                    The tax details.

                  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.

                    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 billing and regular billing. A plan can have at most two trial cycles and only one regular 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.

                    Maximum value: 999.

                  • fixed_price

                    object

                    The fixed amount to charge for the subscription. The changes to fixed amount are applicable to both existing and future subscriptions. For existing subscriptions, payments within 10 days of price change are not affected.

                  • pricing_model

                    enum

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

                    The possible values are:

                    • VOLUME. A volume pricing model.
                    • TIERED. A tiered pricing model.

                    Minimum length: 1.

                    Maximum length: 24.

                    Pattern: ^[A-Z_]+$.

                  • tiers

                    array (contains the pricing_tier object)

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

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

                  pricing_tier

                  • starting_quantity

                    string

                    required

                    The starting quantity for the tier.

                    Minimum length: 1.

                    Maximum length: 32.

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

                  • ending_quantity

                    string

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

                    Minimum length: 1.

                    Maximum length: 32.

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

                  • amount

                    object

                    required

                    The pricing amount for the tier.

                  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.

                  shipping_type

                  • shipping_type

                    enum

                    The method by which the payer wants to get their items.

                    The possible values are:

                    • SHIPPING. The payer intends to receive the items at a specified address.
                    • PICKUP. The payer intends to pick up the items at a specified address. For example, a store address.

                  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.

                  • payer_id

                    string

                    The PayPal-assigned ID for the payer.

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

                  • shipping_address

                    object

                    The shipping details.

                  • payment_source

                    object

                    The payment source used to fund the payment.

                  subscriber_request

                  • 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_id

                    string

                    The PayPal-assigned ID for the payer.

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

                  • shipping_address

                    object

                    The shipping details.

                  • payment_source

                    object

                    The payment source definition. To be eligible to create subscription using debit or credit card, you will need to sign up here (https://www.paypal.com/bizsignup/entry/product/ppcp). Please note, its available only for non-3DS cards and for merchants in US and AU regions.

                  subscription

                  • status

                    string

                    The status of the subscription.

                    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.

                  • id

                    string

                    The PayPal-generated ID for the subscription.

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

                  • billing_info

                    object

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

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

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

                  • custom_id

                    string

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

                    Minimum length: 1.

                    Maximum length: 127.

                    Pattern: ^[\x20-\x7E]+.

                  • plan_overridden

                    boolean

                    Indicates whether the subscription has overridden any plan attributes.

                  • plan

                    object

                    Inline plan details.

                  • links

                    array (contains the link_description object)

                    An array of request-related HATEOAS links.

                  subscription_activate_request

                  • reason

                    string

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

                    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.

                    Maximum value: 999.

                  • last_failed_payment

                    object

                    The details for the last failed payment of the subscription.

                    Read only.

                  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.

                    Maximum value: 500000000.

                  • total_pages

                    integer

                    The total number of pages.

                    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.

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

                  • custom_id

                    string

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

                    Minimum length: 1.

                    Maximum length: 127.

                    Pattern: ^[\x20-\x7E]+.

                  • plan

                    object

                    An inline plan object to customise the subscription. You can override plan level default attributes by providing customised values for the subscription in this object.

                  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.

                  • plan

                    object

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

                  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.

                  • plan

                    object

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

                  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.

                    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_revise_response

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

                  • shipping_amount

                    object

                    The shipping charges.

                  • shipping_address

                    object

                    The shipping address of the subscriber.

                  • plan

                    object

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

                  • plan_overridden

                    boolean

                    Indicates whether the subscription has overridden any plan attributes.

                  • links

                    array (contains the link_description object)

                    An array of request-related HATEOAS links.

                  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.

                  taxes_override

                  • percentage

                    string

                    The tax percentage on the billing amount.

                  • inclusive

                    boolean

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

                  transaction

                  • status

                    string

                    The status of the captured payment.

                  • id

                    string

                    The PayPal-generated transaction ID.

                    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.

                  • payer_email

                    string

                    The email ID of the customer.

                    Minimum length: 3.

                    Maximum length: 254.

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

                  • time

                    string

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

                  transactions_list

                  • transactions

                    array (contains the transaction object)

                    An array of transactions.

                  • total_items

                    integer

                    The total number of items.

                    Maximum value: 500000000.

                  • total_pages

                    integer

                    The total number of pages.

                    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

                  Additional API information