{
  "openapi": "3.2.0",
  "info": {
    "title": "Billing Plans",
    "description": "<blockquote><strong>Deprecation notice:</strong> The <code>/v1/payments/billing-plans</code> endpoints are deprecated. Use the <code>/v1/billing/plans</code> endpoints instead. For details, see <a href=\"/docs/subscriptions/integrate/\">Subscriptions Integration</a>.</blockquote>You use billing plans and billing agreements to create an agreement for a recurring PayPal or debit card payment for goods or services.<br/><br/>A billing plan includes payment definitions and other details. A plan can include only one regular payment definition and, optionally, a trial payment definition. Each definition determines how often and for how long a customer is charged.<br/><br/>A plan can specify a type, which indicates whether the payment definitions in the plan have a fixed or infinite number of payment cycles. The plan also defines merchant preferences including how much it costs to set up the agreement, the links where a customer can approve or can cancel the agreement, and the action if the customer's initial payment fails.<br/><br/>By default, a plan is not active when you create it. To activate it, you update its <code>state</code> to <code>ACTIVE</code>.<br/><br/>For more information, see <a href=\"/docs/subscriptions/integrate/\">Billing Plans and Agreements</a>.<blockquote><strong>Important:</strong> The use of the PayPal REST <code>/payments</code> APIs to accept credit card payments is restricted. Instead, you can accept credit card payments with <a href=\"https://www.braintreepayments.com/products/braintree-direct\">Braintree Direct</a>.</blockquote>",
    "version": "1.2",
    "x-serviceName": "subnplanmgmtserv",
    "x-publicDocsPath": "billing-plans"
  },
  "externalDocs": {
    "url": "/docs/subscriptions/integrate/"
  },
  "servers": [
    {
      "url": "https://api-m.sandbox.paypal.com",
      "description": "PayPal API Sandbox"
    }
  ],
  "tags": [
    {
      "name": "billing-plans",
      "description": "Use the `/billing-plans` resource to create, update, show details for, and list plans."
    }
  ],
  "paths": {
    "/billing-plans/{plan_id}": {
      "get": {
        "tags": [
          "billing-plans"
        ],
        "summary": "Show billing plan details",
        "description": "Shows details for a billing plan, by ID.",
        "operationId": "billing-plans.get",
        "parameters": [
          {
            "name": "plan_id",
            "in": "path",
            "description": "The ID of the billing plan for which to show details.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows plan details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/plan"
                }
              }
            }
          },
          "default": {
            "description": "The error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            }
          }
        },
        "security": [
          {
            "Oauth2": [
              "https://uri.paypal.com/services/subscriptions"
            ]
          }
        ],
        "x-slo": {
          "response_time_95th_percentile": 0,
          "error_rate": 0.1
        },
        "x-visibility": {
          "extent": "EXTERNAL"
        },
        "x-publicSDKSamples": [
          {
            "language": "C#",
            "link": "https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanGet.aspx.cs"
          },
          {
            "language": "JAVA",
            "link": "https://github.com/paypal/PayPal-Java-SDK/blob/master/rest-api-sample/src/main/java/com/paypal/api/sample/SubscriptionSample.java#L74"
          },
          {
            "language": "Node",
            "link": "https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/get.js"
          },
          {
            "language": "PHP",
            "link": "https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/GetPlan.php"
          },
          {
            "language": "Python",
            "link": "https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/get.py"
          }
        ]
      },
      "patch": {
        "tags": [
          "billing-plans"
        ],
        "summary": "Update billing plan",
        "description": "Updates fields in a billing plan, by ID. In the JSON request body, include a patch object that specifies the operation to perform, one or more fields to update, and a new value for each updated field.",
        "operationId": "billing-plans.patch",
        "parameters": [
          {
            "name": "plan_id",
            "in": "path",
            "description": "The ID of the billing plan to update.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/patch_request"
                  },
                  {
                    "type": "object",
                    "examples": [
                      [
                        {
                          "op": "replace",
                          "path": "/",
                          "value": {
                            "state": "ACTIVE"
                          }
                        }
                      ]
                    ]
                  }
                ]
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "A successful request returns the HTTP `200 OK` status code with no JSON response body.",
            "content": {}
          },
          "default": {
            "description": "The error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            }
          }
        },
        "security": [
          {
            "Oauth2": [
              "https://uri.paypal.com/services/subscriptions"
            ]
          }
        ],
        "x-slo": {
          "response_time_95th_percentile": 0,
          "error_rate": 0.1
        },
        "x-visibility": {
          "extent": "EXTERNAL"
        },
        "x-publicSDKSamples": [
          {
            "language": "C#",
            "link": "https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanUpdate.aspx.cs"
          },
          {
            "language": "JAVA",
            "link": "https://github.com/paypal/PayPal-Java-SDK/blob/master/rest-api-sample/src/main/java/com/paypal/api/sample/SubscriptionSample.java#L51"
          },
          {
            "language": "Node",
            "link": "https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/update.js"
          },
          {
            "language": "PHP",
            "link": "https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/UpdatePlan.php"
          },
          {
            "language": "Python",
            "link": "https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/replace.py"
          }
        ],
        "x-codegen-request-body-name": "patch_request"
      }
    },
    "/billing-plans": {
      "get": {
        "tags": [
          "billing-plans"
        ],
        "summary": "List billing plans",
        "description": "Lists billing plans. To filter the plans that appear in the response, specify one or more optional query and pagination parameters.",
        "operationId": "billing-plans.list",
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "The zero-indexed number of the first page that begins the set of pages that are returned in the response.",
            "schema": {
              "type": "string",
              "default": "0"
            }
          },
          {
            "name": "status",
            "in": "query",
            "description": "Filters the plans in the response by a plan status.",
            "schema": {
              "type": "string",
              "default": "CREATED",
              "enum": [
                "CREATED",
                "ACTIVE",
                "INACTIVE",
                "ALL"
              ],
              "x-visibility": {
                "extent": "EXTERNAL"
              }
            },
            "x-visibility": {
              "extent": "EXTERNAL"
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "description": "The number of plans to list on a single page. For example, if `page_size` is `10`, each page shows ten plans. A valid value is a non-negative, non-zero integer.",
            "schema": {
              "type": "string",
              "default": "10"
            }
          },
          {
            "name": "total_required",
            "in": "query",
            "description": "Indicates whether the response includes the `total_items` and `total_pages` fields. Value is `yes` or `no`.",
            "schema": {
              "type": "string",
              "default": "no"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists plans with details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/plan_list"
                }
              }
            }
          },
          "default": {
            "description": "The error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            }
          }
        },
        "security": [
          {
            "Oauth2": [
              "https://uri.paypal.com/services/subscriptions"
            ]
          }
        ],
        "x-slo": {
          "response_time_95th_percentile": 0,
          "error_rate": 0.1
        },
        "x-visibility": {
          "extent": "EXTERNAL"
        },
        "x-publicSDKSamples": [
          {
            "language": "C#",
            "link": "https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanGetList.aspx.cs"
          },
          {
            "language": "Node",
            "link": "https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/list.js"
          },
          {
            "language": "PHP",
            "link": "https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/ListPlans.php"
          },
          {
            "language": "Python",
            "link": "https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/get_all.py"
          }
        ]
      },
      "post": {
        "tags": [
          "billing-plans"
        ],
        "summary": "Create billing plan",
        "description": "Creates a billing plan. In the JSON request body, include the plan details. A plan must include at least one regular payment definition and, optionally, a trial payment definition. Each payment definition specifies a billing period, which determines how often and for how long the customer is charged. A plan can specify a fixed or infinite number of payment cycles. A payment definition can optionally specify shipping fee and tax amounts. The default state of a new plan is `CREATED`. Before you can create an agreement from a plan, you must activate the plan by updating its `state` to `ACTIVE`.",
        "operationId": "billing-plans.post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/plan"
                  },
                  {
                    "type": "object",
                    "examples": [
                      {
                        "name": "Simple Plan",
                        "description": "Plan with one regular payment definition, minimal merchant preferences, and no shipping fees or tax.",
                        "type": "FIXED",
                        "payment_definitions": [
                          {
                            "name": "Regular payment definition",
                            "type": "REGULAR",
                            "frequency": "MONTH",
                            "frequency_interval": "2",
                            "amount": {
                              "value": "100",
                              "currency": "USD"
                            },
                            "cycles": "12"
                          }
                        ],
                        "merchant_preferences": {
                          "return_url": "https://example.com",
                          "cancel_url": "https://example.com/cancel"
                        }
                      }
                    ]
                  }
                ]
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows plan details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/plan"
                }
              }
            }
          },
          "default": {
            "description": "The error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            }
          }
        },
        "security": [
          {
            "Oauth2": [
              "https://uri.paypal.com/services/subscriptions"
            ]
          }
        ],
        "x-slo": {
          "response_time_95th_percentile": 0,
          "error_rate": 0.1
        },
        "x-visibility": {
          "extent": "EXTERNAL"
        },
        "x-publicSDKSamples": [
          {
            "language": "C#",
            "link": "https://github.com/paypal/PayPal-NET-SDK/blob/develop/Samples/Source/BillingPlanCreate.aspx.cs"
          },
          {
            "language": "JAVA",
            "link": "https://github.com/paypal/PayPal-Java-SDK/blob/master/rest-api-sample/src/main/java/com/paypal/api/sample/SubscriptionSample.java#L35"
          },
          {
            "language": "Node",
            "link": "https://github.com/paypal/PayPal-node-SDK/blob/master/samples/subscription/billing_plans/create.js"
          },
          {
            "language": "PHP",
            "link": "https://github.com/paypal/PayPal-PHP-SDK/blob/master/sample/billing/CreatePlan.php"
          },
          {
            "language": "Python",
            "link": "https://github.com/paypal/PayPal-Python-SDK/blob/master/samples/subscription/billing_plans/create.py"
          }
        ],
        "x-codegen-request-body-name": "plan"
      }
    }
  },
  "components": {
    "schemas": {
      "plan": {
        "title": "Plan",
        "required": [
          "description",
          "name",
          "type"
        ],
        "type": "object",
        "properties": {
          "id": {
            "maxLength": 128,
            "type": "string",
            "description": "The ID of the plan.",
            "readOnly": true
          },
          "name": {
            "maxLength": 128,
            "type": "string",
            "description": "The plan name."
          },
          "description": {
            "maxLength": 127,
            "type": "string",
            "description": "The plan description. Maximum length is 127 single-byte alphanumeric characters."
          },
          "type": {
            "maxLength": 20,
            "type": "string",
            "description": "The plan type. Indicates whether the payment definitions in the plan have a fixed number of or infinite payment cycles. Value is:<ul><li><code>FIXED</code>. The plan has a fixed number of payment cycles.</li><li><code>INFINITE</code>. The plan has infinite, or <code>0</code>, payment cycles.</li></ul>",
            "enum": [
              "FIXED",
              "INFINITE"
            ]
          },
          "state": {
            "type": "string",
            "description": "The plan status.",
            "readOnly": true,
            "default": "CREATED",
            "enum": [
              "CREATED",
              "ACTIVE",
              "INACTIVE"
            ]
          },
          "create_time": {
            "type": "string",
            "description": "The date and time when the plan was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
            "readOnly": true
          },
          "update_time": {
            "type": "string",
            "description": "The date and time when the plan was updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).",
            "readOnly": true
          },
          "payment_definitions": {
            "type": "array",
            "description": "A payment definition, which determines how often and for how long the customer is charged. Includes the interval at which the customer is charged, the charge amount, and optional shipping fees and taxes.",
            "items": {
              "type": "object",
              "allOf": [
                {
                  "type": "object",
                  "x-publicDocsSchemaName": "payment_definition"
                },
                {
                  "$ref": "#/components/schemas/payment_definition"
                }
              ]
            }
          },
          "terms": {
            "type": "array",
            "description": "An array of terms for this plan. Read-only and reserved for future use.",
            "readOnly": true,
            "items": {
              "type": "object",
              "allOf": [
                {
                  "type": "object",
                  "x-publicDocsSchemaName": "term"
                },
                {
                  "$ref": "#/components/schemas/terms"
                }
              ]
            }
          },
          "merchant_preferences": {
            "$ref": "#/components/schemas/merchant_preferences"
          },
          "links": {
            "type": "array",
            "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
            "readOnly": true,
            "items": {
              "type": "object",
              "allOf": [
                {
                  "$ref": "#/components/schemas/link_description"
                },
                {
                  "type": "object",
                  "x-publicDocsSchemaName": "link_description"
                }
              ]
            }
          }
        },
        "description": "The billing plan details. You can base one or more agreements on an active plan.",
        "x-visibility": {
          "extent": "EXTERNAL"
        },
        "x-links": [
          {
            "rel": "self",
            "href": "plan/{id}",
            "method": "GET"
          }
        ]
      },
      "error": {
        "title": "Error",
        "required": [
          "information_link",
          "message",
          "name"
        ],
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The human-readable, unique name of the error.",
            "readOnly": true
          },
          "debug_id": {
            "type": "string",
            "description": "The PayPal internal ID. Used for correlation purposes.",
            "readOnly": true
          },
          "message": {
            "type": "string",
            "description": "The message that describes the error.",
            "readOnly": true
          },
          "information_link": {
            "type": "string",
            "description": "The URI to detailed information related to this error for the developer.",
            "readOnly": true
          },
          "details": {
            "type": "array",
            "description": "An array of additional details for the error.",
            "readOnly": true,
            "items": {
              "type": "object",
              "allOf": [
                {
                  "$ref": "#/components/schemas/error_details"
                },
                {
                  "type": "object",
                  "x-publicDocsSchemaName": "error_details"
                }
              ]
            }
          }
        },
        "description": "The error information."
      },
      "patch_request": {
        "title": "Patch Request",
        "type": "array",
        "description": "An array of JSON patch objects to apply partial updates to resources.",
        "items": {
          "type": "object",
          "allOf": [
            {
              "$ref": "#/components/schemas/patch"
            },
            {
              "type": "object",
              "x-publicDocsSchemaName": "patch"
            }
          ]
        }
      },
      "plan_list": {
        "title": "Plan List",
        "type": "object",
        "properties": {
          "plans": {
            "type": "array",
            "description": "An array of plans.",
            "items": {
              "type": "object",
              "allOf": [
                {
                  "$ref": "#/components/schemas/plan"
                },
                {
                  "type": "object",
                  "x-publicDocsSchemaName": "plan"
                }
              ]
            }
          },
          "total_items": {
            "type": "string",
            "description": "The total number of plans in the list.",
            "readOnly": true
          },
          "total_pages": {
            "type": "string",
            "description": "The total number of pages in the response. The `page_size` request value determines how many plans appear on each page. The `total_items` and `page_size` request values are used to calculate the total number of pages in the response.",
            "readOnly": true
          },
          "links": {
            "type": "array",
            "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
            "readOnly": true,
            "items": {
              "type": "object",
              "allOf": [
                {
                  "$ref": "#/components/schemas/link_description"
                },
                {
                  "type": "object",
                  "x-publicDocsSchemaName": "link_description"
                }
              ]
            }
          }
        },
        "description": "A list of plans, with details for each plan and a set of [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).",
        "x-visibility": {
          "extent": "EXTERNAL"
        },
        "x-links": [
          {
            "rel": "start",
            "href": "billing-plans?page_size={page_size}&page={page}&start={start_id}&status={status}",
            "method": "GET"
          },
          {
            "rel": "next",
            "href": "billing-plans?page_size={page_size}&page={page+1}&status={status}",
            "method": "GET"
          },
          {
            "rel": "prev",
            "href": "billing-plans?page_size={page_size}&page={page-1}&status={status}",
            "method": "GET"
          },
          {
            "rel": "last",
            "href": "billing-plans?page_size={page_size}&page={last}&status={status}",
            "method": "GET"
          }
        ]
      },
      "payment_definition": {
        "title": "Payment Definition",
        "required": [
          "amount",
          "cycles",
          "frequency",
          "frequency_interval",
          "name",
          "type"
        ],
        "type": "object",
        "properties": {
          "id": {
            "maxLength": 128,
            "type": "string",
            "description": "The ID of the payment definition.",
            "readOnly": true
          },
          "name": {
            "maxLength": 128,
            "type": "string",
            "description": "The payment definition name."
          },
          "type": {
            "type": "string",
            "description": "The payment definition type. Each plan must have at least one regular payment definition and, optionally, a trial payment definition. Each definition specifies how often and for how long the customer is charged.",
            "enum": [
              "TRIAL",
              "REGULAR"
            ]
          },
          "frequency_interval": {
            "type": "string",
            "description": "The interval at which the customer is charged. Value cannot be greater than 12 months."
          },
          "frequency": {
            "type": "string",
            "description": "The frequency of the payment in this definition.",
            "enum": [
              "WEEK",
              "DAY",
              "YEAR",
              "MONTH"
            ]
          },
          "cycles": {
            "type": "string",
            "description": "The number of payment cycles. For infinite plans with a regular payment definition, set `cycles` to `0`."
          },
          "charge_models": {
            "type": "array",
            "description": "An array of shipping fees and taxes.",
            "items": {
              "type": "object",
              "allOf": [
                {
                  "type": "object",
                  "x-publicDocsSchemaName": "charge_model"
                },
                {
                  "$ref": "#/components/schemas/charge_models"
                }
              ]
            }
          },
          "amount": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/currency"
              },
              {
                "type": "object",
                "description": "The currency and amount of the charge to make at the end of each payment cycle for this definition."
              }
            ]
          }
        },
        "description": "A payment definition, which determines how often and for how long the customer is charged. Includes the interval at which the customer is charged, the charge amount, and optional shipping fees and taxes.",
        "x-visibility": {
          "extent": "EXTERNAL"
        }
      },
      "terms": {
        "title": "Terms",
        "required": [
          "amount_range",
          "buyer_editable",
          "max_billing_amount",
          "occurrences",
          "type"
        ],
        "type": "object",
        "properties": {
          "id": {
            "maxLength": 128,
            "type": "string",
            "description": "The ID of the terms.",
            "readOnly": true
          },
          "type": {
            "type": "string",
            "description": "The term type.",
            "enum": [
              "MONTHLY",
              "WEEKLY",
              "YEARLY"
            ]
          },
          "occurrences": {
            "type": "string",
            "description": "The number of times that money can be pulled during this term."
          },
          "buyer_editable": {
            "type": "string",
            "description": "Indicates whether the customer can edit the amount in this term."
          },
          "max_billing_amount": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/currency"
              },
              {
                "type": "object",
                "description": "The currency and amount of the maximum billing amount for this term."
              }
            ]
          },
          "amount_range": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/currency"
              },
              {
                "type": "object",
                "description": "The currency and amount range for this term."
              }
            ]
          }
        },
        "description": "The terms for the plan.",
        "x-visibility": {
          "extent": "EXTERNAL"
        }
      },
      "merchant_preferences": {
        "title": "Merchant Preferences",
        "required": [
          "cancel_url",
          "return_url"
        ],
        "type": "object",
        "properties": {
          "cancel_url": {
            "maxLength": 1000,
            "type": "string",
            "description": "The URL where the customer can cancel the agreement.",
            "format": "uri"
          },
          "return_url": {
            "maxLength": 1000,
            "type": "string",
            "description": "The URL where the customer can approve the agreement.",
            "format": "uri"
          },
          "notify_url": {
            "maxLength": 1000,
            "type": "string",
            "description": "The URL where the customer is notified that the agreement was created. Read-only and reserved for future use.",
            "format": "uri",
            "readOnly": true
          },
          "max_fail_attempts": {
            "type": "string",
            "description": "The maximum number of allowed failed payment attempts. The default value, which is `0`, defines infinite failed payment attempts.",
            "default": "0"
          },
          "auto_bill_amount": {
            "type": "string",
            "description": "Indicates whether PayPal automatically bills the outstanding balance in the next billing cycle. The outstanding balance is the total amount of any previously failed scheduled payments. Value is:<ul><li><code>NO</code>. PayPal does not automatically bill the customer the outstanding balance.</li><li><code>YES</code>. PayPal automatically bills the customer the outstanding balance.</li></ul>",
            "default": "NO",
            "enum": [
              "YES",
              "NO"
            ]
          },
          "initial_fail_amount_action": {
            "type": "string",
            "description": "The action if the customer's initial payment fails. Value is:<ul><li><code>CONTINUE</code>. The agreement remains active and the failed payment amount is added to the outstanding balance. If auto-billing is enabled, PayPal automatically bills the outstanding balance in the next billing cycle.</li><li><code>CANCEL</code> PayPal creates the agreement but sets its state to pending until the initial payment clears. If the initial payment clears, the pending agreement becomes active. If the initial payment fails, the pending agreement is canceled.</li></ul><blockquote><strong>Note:</strong> You can use the `setup_fee` value as the initial amount to trigger the `initial_fail_amount_action`.</blockquote>",
            "default": "CONTINUE",
            "enum": [
              "CONTINUE",
              "CANCEL"
            ]
          },
          "accepted_payment_type": {
            "type": "string",
            "description": "The payment types that are accepted for this plan. Read-only and reserved for future use.",
            "readOnly": true
          },
          "char_set": {
            "type": "string",
            "description": "The character set for this plan. Read-only and reserved for future use.",
            "readOnly": true
          },
          "setup_fee": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/currency"
              },
              {
                "type": "object",
                "description": "The currency and amount of the set-up fee for the agreement. This fee is the initial, non-recurring payment amount that is due immediately when the billing agreement is created. Can be used as the initial amount to trigger the `initial_fail_amount_action`. The default for the amount is `0`."
              }
            ]
          }
        },
        "description": "The merchant preferences for a plan, which define how much it costs to set up the agreement, the URLs where the customer can approve or cancel the agreement, the maximum number of allowed failed payment attempts, whether PayPal automatically bills the outstanding balance in the next billing cycle, and the action if the customer's initial payment fails.",
        "x-visibility": {
          "extent": "EXTERNAL"
        }
      },
      "link_description": {
        "title": "Link Description",
        "required": [
          "href",
          "rel"
        ],
        "type": "object",
        "properties": {
          "href": {
            "type": "string",
            "description": "The complete target URL. To make the related call, combine the method with this [URI Template-formatted](https://tools.ietf.org/html/rfc6570) link. For pre-processing, include the `$`, `(`, and `)` characters. The `href` is the key HATEOAS component that links a completed call with a subsequent call.",
            "x-visibility": {
              "extent": "EXTERNAL"
            }
          },
          "rel": {
            "type": "string",
            "description": "The [link relation type](https://tools.ietf.org/html/rfc5988#section-4), which serves as an ID for a link that unambiguously describes the semantics of the link. See [Link Relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml).",
            "x-visibility": {
              "extent": "EXTERNAL"
            }
          },
          "method": {
            "type": "string",
            "description": "The HTTP method required to make the related call.",
            "enum": [
              "GET",
              "POST",
              "PUT",
              "DELETE",
              "HEAD",
              "CONNECT",
              "OPTIONS",
              "PATCH"
            ],
            "x-visibility": {
              "extent": "EXTERNAL"
            }
          }
        },
        "description": "The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information."
      },
      "currency": {
        "title": "Currency",
        "required": [
          "currency",
          "value"
        ],
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "description": "The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/)."
          },
          "value": {
            "type": "string",
            "description": "The value, which might be:<ul><li>An integer for currencies like `JPY` that are not typically fractional.</li><li>A decimal fraction for currencies like `TND` that are subdivided into thousandths.</li></ul>For the required number of decimal places for a currency code, see [Currency codes - ISO 4217](https://www.iso.org/iso-4217-currency-codes.html)."
          }
        },
        "description": "The currency and amount for a financial transaction, such as a balance or payment due."
      },
      "charge_models": {
        "title": "Charge Model",
        "required": [
          "amount",
          "type"
        ],
        "type": "object",
        "properties": {
          "id": {
            "maxLength": 128,
            "type": "string",
            "description": "The ID of the charge model.",
            "readOnly": true
          },
          "type": {
            "maxLength": 20,
            "type": "string",
            "description": "The charge model type, which is tax or shipping.",
            "enum": [
              "TAX",
              "SHIPPING"
            ]
          },
          "amount": {
            "type": "object",
            "allOf": [
              {
                "$ref": "#/components/schemas/currency"
              },
              {
                "type": "object",
                "description": "The currency and amount of the shipping fee or tax."
              }
            ]
          }
        },
        "description": "The shipping fee and tax information.",
        "x-visibility": {
          "extent": "EXTERNAL"
        }
      },
      "error_details": {
        "title": "Error Details",
        "required": [
          "field",
          "issue"
        ],
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "The name of the field that caused the error."
          },
          "issue": {
            "type": "string",
            "description": "The reason for the error."
          }
        },
        "description": "The error details. Required for client-side `4XX` errors."
      },
      "patch": {
        "title": "Patch",
        "required": [
          "op"
        ],
        "type": "object",
        "properties": {
          "op": {
            "type": "string",
            "description": "The operation.",
            "x-enum": [
              {
                "value": "add",
                "description": "Depending on the target location reference, completes one of these functions:<ul><li><strong>The target location is an array index</strong>. Inserts a new value into the array at the specified index.</li><li><strong>The target location is an object parameter that does not already exist</strong>. Adds a new parameter to the object.</li><li><strong>The target location is an object parameter that does exist</strong>. Replaces that parameter's value.</li></ul>The <code>value</code> parameter defines the value to add. For more information, see <a href=\"https://tools.ietf.org/html/rfc6902#section-4.1\">4.1. add</a>."
              },
              {
                "value": "remove",
                "description": "Removes the value at the target location. For the operation to succeed, the target location must exist. For more information, see <a href=\"https://tools.ietf.org/html/rfc6902#section-4.2\">4.2. remove</a>."
              },
              {
                "value": "replace",
                "description": "Replaces the value at the target location with a new value. The operation object must contain a <code>value</code> parameter that defines the replacement value. For the operation to succeed, the target location must exist. For more information, see <a href=\"https://tools.ietf.org/html/rfc6902#section-4.3\">4.3. replace</a>."
              },
              {
                "value": "move",
                "description": "Removes the value at a specified location and adds it to the target location. The operation object must contain a <code>from</code> 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 <code>from</code> location must exist. For more information, see <a href=\"https://tools.ietf.org/html/rfc6902#section-4.4\">4.4. move</a>."
              },
              {
                "value": "copy",
                "description": "Copies the value at a specified location to the target location. The operation object must contain a <code>from</code> 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 <code>from</code> location must exist. For more information, see <a href=\"https://tools.ietf.org/html/rfc6902#section-4.5\">4.5. copy</a>."
              },
              {
                "value": "test",
                "description": "Tests that a value at the target location is equal to a specified value. The operation object must contain a <code>value</code> 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 <code>value</code> value. For test, <code>equal</code> indicates that the value at the target location and the value that <code>value</code> defines are of the same JSON type. The data type of the value determines how equality is defined:<table><thead align=\"left\"><tr><th>Type</th><th>Considered equal if both values</th></tr></thead><tbody align=\"left\"><tr><td><strong>strings</strong></td><td>Contain the same number of Unicode characters and their code points are byte-by-byte equal.</td></tr><tr><td><strong>numbers</strong></td><td>Are numerically equal.</td></tr><tr><td><strong>arrays</strong></td><td>Contain the same number of values, and each value is equal to the value at the corresponding position in the other array, by using these type-specific rules.</td></tr><tr><td><strong>objects</strong></td><td>Contain the same number of parameters, and each parameter is equal to a parameter in the other object, by comparing their keys (as strings) and their values (by using these type-specific rules).</td></tr><tr><td><strong>literals (<code>false</code>, <code>true</code>, and <code>null</code>)</strong></td><td>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.</td></tr></tbody></table>For more information, see <a href=\"https://tools.ietf.org/html/rfc6902#section-4.6\">4.6. test</a>."
              }
            ]
          },
          "path": {
            "type": "string",
            "description": "The <a href=\"https://tools.ietf.org/html/rfc6901\">JSON Pointer</a> to the target document location at which to complete the operation."
          },
          "value": {
            "title": "Patch Value",
            "type": "object",
            "properties": {},
            "description": "The value to apply. The <code>remove</code> operation does not require a value."
          },
          "from": {
            "type": "string",
            "description": "The <a href=\"https://tools.ietf.org/html/rfc6901\">JSON Pointer</a> to the target document location from which to move the value. Required for the <code>move</code> operation."
          }
        },
        "description": "The JSON patch object to apply partial updates to resources."
      }
    },
    "securitySchemes": {
      "Oauth2": {
        "type": "oauth2",
        "description": "Oauth 2.0 authentication",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "/api/oauth-proxy",
            "scopes": {
              "https://uri.paypal.com/services/subscriptions": "Create and manage a plan"
            }
          }
        }
      }
    }
  },
  "x-deprecated": {
    "see": "v1/billing/plans",
    "since_version": "1.2"
  },
  "x-errors": [
    {
      "name": "INTERNAL_SERVICE_ERROR",
      "message": "An internal service error has occurred.",
      "description": "Resend the request at another time. If this error continues, contact [PayPal Merchant Technical Support](https://developer.paypal.com/webapps/developer/support)."
    },
    {
      "name": "REQUIRED_SCOPE_MISSING",
      "message": "Access token does not have required scope.",
      "description": "Use the scope required for this request type to get buyer consent."
    },
    {
      "name": "UNAUTHORIZED_ACCESS",
      "message": "You don't have permission to access this resource.",
      "description": "Pass a valid plan ID."
    },
    {
      "name": "VALIDATION_ERROR",
      "message": "Invalid request - see details.",
      "description": "A validation issue occurred with your request."
    }
  ],
  "x-requestValidationIssues": [
    {
      "name": "RequiredFieldMissing",
      "message": "Required field missing."
    },
    {
      "name": "TMP_NAME_FIELD_MISSING",
      "message": "Field is mandatory. Limit of 127 characters."
    },
    {
      "name": "TMP_DESC_FIELD_MISSING",
      "message": "Field is mandatory. Limit of 127 characters."
    },
    {
      "name": "TMP_INVALID_PDS",
      "message": "Payment definitions are invalid. Valid parameters are REGULAR or combination of TRIAL and REGULAR."
    },
    {
      "name": "TMP_INVALID_TYPE",
      "message": "Template type is either null or invalid. Valid parameters are UNLIMITED or FIXED."
    },
    {
      "name": "QUERYPARAM_INVALID_PAGE_SIZE",
      "message": "Invalid Page size, valid value is positive number less than 21."
    },
    {
      "name": "INVALID_REGULAR_AMOUNT",
      "message": "Amount passed in regular payment definition should be more than zero."
    },
    {
      "name": "PD_INVALID_CURRENCY_OBJECT",
      "message": "Currency object of payment definition can't be null."
    },
    {
      "name": "QUERYPARAM_INVALID_TOTAL_REQUIRED",
      "message": "Invalid Total required, valid value are yes or no."
    },
    {
      "name": "TMP_INVALID_MPREF",
      "message": "Merchant preferences are mandatory."
    },
    {
      "name": "PD_INVALID_NAME",
      "message": "Field is mandatory. Limit of 127 characters."
    },
    {
      "name": "PD_INVALID_TYPE",
      "message": "Payment Definition type passed is either null/invalid. Valid values are TRIAL or REGULAR."
    },
    {
      "name": "PD_INVALID_FREQ",
      "message": "Payment Definition Frequency type passed is either null/invalid. Valid values are DAY, WEEK, MONTH or YEAR."
    },
    {
      "name": "PD_INVALID_FREQ_COUNT",
      "message": "Payment Definition Frequency count should be positive numeric."
    },
    {
      "name": "PD_INVALID_CYCLES",
      "message": "Number of Cycles should be positive numeric and less than 10000."
    },
    {
      "name": "PD_INVALID_AMT",
      "message": "Amount should a positive number greater than 0 with a maximum of 2 decimal places separated by '.', optional thousands separator ',', limited to 7 digits before the decimal point."
    },
    {
      "name": "PD_INVALID_CMLIST",
      "message": "Charge Models within a payment definition should have distinct 'Types'."
    },
    {
      "name": "AMT_BLANK",
      "message": "Amount cannot be blank."
    },
    {
      "name": "CM_INVALID_TYPE",
      "message": "Charge Model type is invalid or null. Valid parameters are SHIPPING or TAX."
    },
    {
      "name": "CM_INVALID_AMOUNT",
      "message": "Charge Model amount should be non-negative number with a maximum of 2 decimal places separated by '.', optional thousands separator ',', limited to 7 digits before the decimal point."
    },
    {
      "name": "CM_INVALID_ID",
      "message": "Charge Model id should not be null or blank."
    },
    {
      "name": "MP_INVALID_AUTOBILL",
      "message": "invalid autobill_amount type. Can be yes or no."
    },
    {
      "name": "MP_INVALID_INIT_FAIL_AMT_ACTION",
      "message": "Invalid init amount action. Valid values are CANCEL, CONTINUE."
    },
    {
      "name": "QUERYPARAM_INVALID_SORT_ORDER",
      "message": "Sort order is invalid, valid values are asc / desc."
    },
    {
      "name": "QUERYPARAM_INVALID_STATUS",
      "message": "Invalid status, valid values are CREATED, ACTIVE, INACTIVE."
    },
    {
      "name": "TEMPLATE_ID_INVALID",
      "message": "Incorrect Template Id."
    },
    {
      "name": "SET_UP_FEE",
      "message": "setup_fee is invalid/null.It should be positive number with max value 9999999."
    },
    {
      "name": "AUTO_BILL_AMT",
      "message": "Invalid autobill_amount type. Can be yes or no."
    },
    {
      "name": "FAIL_INIT_AMT_ACTION",
      "message": "Invalid fail_initamt_action. Can be continue or cancel."
    },
    {
      "name": "MAX_FAIL_ATTEMPTS",
      "message": "max_fail_attempts is invalid/null.It should be positive integer with max value 999."
    },
    {
      "name": "INVALID_URL",
      "message": "Missing/Invalid URL entered.Max length is 2048."
    },
    {
      "name": "AUTO_BILL_AMT",
      "message": "Invalid autobill_amount type. Can be yes or no."
    },
    {
      "name": "INVALID_PLAN_CURRENCIES",
      "message": "All amounts with in a plan should have same currency."
    },
    {
      "name": "CHARGE_MODEL_ID_INVALID",
      "message": "Invalid Charge Model Id."
    },
    {
      "name": "PAYMENT_DEF_ID_INVALID",
      "message": "Invalid payment def Id."
    },
    {
      "name": "INVALID_INFINITE_PD_VALUE",
      "message": "If payment definition type is REGULAR, no_of_cycles can only be null or 0 for an UNLIMITED plan."
    },
    {
      "name": "INVALID_FIXED_PD_VALUE",
      "message": "no_of_cycles can't be null or 0 for a FIXED plan."
    },
    {
      "name": "INVALID_TRIAL_CYCLE_VALUE",
      "message": "For TRIAL payment definition, number of cycles can't be null or 0."
    },
    {
      "name": "INVALID_PD_SPECIFIED",
      "message": "You can't create template with only TRIAL as payment definition."
    },
    {
      "name": "CANT_ACTIVATE_ACTIVE_TEMPLATE",
      "message": "You can't activate an active template."
    },
    {
      "name": "CANT_MODIFY_DELETED_TEMPLATE",
      "message": "Invalid template Id."
    },
    {
      "name": "CANT_DEACTIVATE_INACTIVE_TEMPLATE",
      "message": "You can't deactivate an inactive template."
    },
    {
      "name": "CAN_UPDATE_TEMPLATE_ONLY_IN_CREATED_STATE",
      "message": "Updation of a template only allowed in CREATED state."
    },
    {
      "name": "REMOVE_OPERATION_NOT_SUPPORTED",
      "message": "Remove operation not supported now."
    },
    {
      "name": "ADD_OPERATION_NOT_SUPPORTED",
      "message": "Add operation not supported now."
    },
    {
      "name": "INVALID_OPERATION",
      "message": "Invalid Operation nome. Can be add, remove or replace."
    },
    {
      "name": "INVALID_PATCH_PATH",
      "message": "Invalid Path provided."
    },
    {
      "name": "UNWANTED_FIELD_MESSAGE",
      "message": "patch is not supported for this field."
    },
    {
      "name": "INVALID_STATE",
      "message": "Invalid state entered.Valid values are created/deleted/inactive/active."
    },
    {
      "name": "INVALID_STATE_CHANGE_REQUEST",
      "message": "Requested state change is invalid."
    },
    {
      "name": "TEMPLATE_ALREADY_IN_GIVEN_STATE",
      "message": "Plan already in same state."
    },
    {
      "name": "FREQ_MORE_THAN_YEAR",
      "message": "Frequency more than year is not supported."
    },
    {
      "name": "TEMPLATE_ALREADY_IN_GIVEN_STATE",
      "message": "Plan already in same state."
    },
    {
      "name": "MustNotBeBlank",
      "message": "Must not be blank."
    },
    {
      "name": "InvalidCurrencyCode",
      "message": "Currency code must be 3-character ISO 4217 value (upper case)."
    },
    {
      "name": "InvalidPositiveNumber",
      "message": "Must be a positive integer."
    },
    {
      "name": "InvalidFormatUrl",
      "message": "Invalid URL."
    },
    {
      "name": "InvalidFormatCurrencyAmount",
      "message": "Currency amount must be non-negative number, may optionally contain exactly 2 decimal places separated by '.', optional thousands separator ',', limited to 7 digits before the decimal point."
    },
    {
      "name": "InvalidNumeric",
      "message": "Must be numeric."
    },
    {
      "name": "InvalidAlphanumeric",
      "message": "Must be alphanumeric."
    },
    {
      "name": "InvalidAlphaNumPlus",
      "message": "Must contain only these characters: a-z, A-Z, 0-9, punctuation(.,#-'), and embedded spaces."
    },
    {
      "name": "InvalidDateTimeFormat",
      "message": "Must be a date_time string of form yyyy-mm-ddThh:mm:ss(.sss)?Z."
    },
    {
      "name": "InvalidDateTime",
      "message": "The date_time, although formatted properly, does not represent a valid date_time."
    },
    {
      "name": "InvalidQueryParams",
      "message": "Invalid to specify both start_id and start_index query params."
    },
    {
      "name": "ReadonlyField",
      "message": "Not valid to specify this field in a request."
    },
    {
      "name": "InvalidIntegerFormat",
      "message": "Invalid value."
    },
    {
      "name": "FractionDigitsNotAllowed",
      "message": "Fraction digits are not allowed with this currency."
    }
  ]
}