{ "openapi": "3.0.3", "info": { "title": "Subscriptions", "description": "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.", "version": "1.6", "contact": {} }, "servers": [ { "url": "https://api-m.sandbox.paypal.com", "description": "PayPal Sandbox Environment" }, { "url": "https://api-m.paypal.com", "description": "PayPal Live Environment" } ], "tags": [ { "name": "plans", "description": "Use the `/billing/plans` resource to create and manage plans." }, { "name": "subscriptions", "description": "Use the `/billing/subscriptions` resource to create and manage subscriptions." } ], "externalDocs": { "url": "https://developer.paypal.com/docs/api/subscriptions/v1/" }, "paths": { "/v1/billing/plans": { "post": { "summary": "Create plan", "description": "Creates a plan that defines pricing and billing cycle details for subscriptions.", "operationId": "plans.create", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows billing plan details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan" }, "examples": { "plan": { "value": { "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-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ", "rel": "edit", "method": "PATCH" }, { "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/deactivate", "rel": "deactivate", "method": "POST" }, { "href": "https://api-m.paypal.com/v1/billing/plans/P-5ML4271244454362WXNWU5NQ/update-pricing-schemes", "rel": "edit", "method": "POST" } ] } } } } } }, "201": { "description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows billing plan details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan" } } } }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/plans.create-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/prefer" }, { "$ref": "#/components/parameters/paypal_request_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan_request_POST" }, "examples": { "plan_request_post": { "value": { "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 } } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "plans" ] }, "get": { "summary": "List plans", "description": "Lists billing plans.", "operationId": "plans.list", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that lists billing plans.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/plan_collection" } } } }, "400": { "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_404" } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/prefer" }, { "$ref": "#/components/parameters/product_id" }, { "$ref": "#/components/parameters/plan_ids" }, { "$ref": "#/components/parameters/page_size" }, { "$ref": "#/components/parameters/page" }, { "$ref": "#/components/parameters/total_required" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "plans" ] } }, "/v1/billing/plans/{id}": { "get": { "summary": "Show plan details", "description": "Shows details for a plan, by ID.", "operationId": "plans.get", "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" } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "plans" ] }, "patch": { "summary": "Update plan", "description": "Updates a plan with the `CREATED` or `ACTIVE` status. For an `INACTIVE` plan, you can make only status updates.
You can patch these attributes and objects:
Attribute or objectOperations
descriptionreplace
payment_preferences.auto_bill_outstandingreplace
taxes.percentagereplace
payment_preferences.payment_failure_thresholdreplace
payment_preferences.setup_feereplace
payment_preferences.setup_fee_failure_actionreplace
namereplace
", "operationId": "plans.patch", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/plans.patch-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/plans.patch-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "$ref": "#/components/requestBodies/patch_request" }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "plans" ] } }, "/v1/billing/plans/{id}/activate": { "post": { "summary": "Activate plan", "description": "Activates a plan, by ID.", "operationId": "plans.activate", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/plans.activate-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "plans" ] } }, "/v1/billing/plans/{id}/deactivate": { "post": { "summary": "Deactivate plan", "description": "Deactivates a plan, by ID.", "operationId": "plans.deactivate", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/plans.deactivate-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "plans" ] } }, "/v1/billing/plans/{id}/update-pricing-schemes": { "post": { "summary": "Update pricing", "description": "Updates pricing for a plan. For example, you can update a regular billing cycle from $5 per month to $7 per month.", "operationId": "plans.update-pricing-schemes", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/plans.update-pricing-schemes-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/plans.update-pricing-schemes-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_pricing_schemes_list_request" }, "examples": { "update_pricing_schemes_list_request": { "value": { "pricing_schemes": [ { "billing_cycle_sequence": 1, "pricing_scheme": { "fixed_price": { "value": "50", "currency_code": "USD" } } }, { "billing_cycle_sequence": 2, "pricing_scheme": { "fixed_price": { "value": "100", "currency_code": "USD" }, "pricing_model": "VOLUME", "tiers": [ { "starting_quantity": "1", "ending_quantity": "1000", "amount": { "value": "150", "currency_code": "USD" } }, { "starting_quantity": "1001", "amount": { "value": "250", "currency_code": "USD" } } ] } } ] } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "plans" ] } }, "/v1/billing/subscriptions": { "post": { "summary": "Create subscription", "description": "Creates a subscription.", "operationId": "subscriptions.create", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "subscription": { "value": { "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-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G", "rel": "edit", "method": "PATCH" }, { "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G", "rel": "self", "method": "GET" } ] } } } } } }, "201": { "description": "A successful request returns the HTTP `201 Created` status code and a JSON response body that shows subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" }, "examples": { "subscription": { "value": { "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-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G", "rel": "edit", "method": "PATCH" }, { "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G", "rel": "self", "method": "GET" } ] } } } } } }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.create-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/subscriptions.create-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/prefer" }, { "$ref": "#/components/parameters/paypal_request_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_request_post" }, "examples": { "subscription_request_post": { "value": { "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" } } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } }, "/v1/billing/subscriptions/{id}": { "get": { "summary": "Show subscription details", "description": "Shows details for a subscription, by ID.", "operationId": "subscriptions.get", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription" } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/fields" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] }, "patch": { "summary": "Update subscription", "description": "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.
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
", "operationId": "subscriptions.patch", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.patch-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/subscriptions.patch-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "$ref": "#/components/requestBodies/patch_request" }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } }, "/v1/billing/subscriptions/{id}/revise": { "post": { "summary": "Revise plan or quantity of subscription", "description": "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.", "operationId": "subscriptions.revise", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_revise_response" }, "examples": { "subscription_revise_response": { "value": { "plan_id": "P-5ML4271244454362WXNWU5NQ", "plan_overridden": false, "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-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G", "rel": "edit", "method": "PATCH" }, { "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G", "rel": "self", "method": "GET" }, { "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/cancel", "rel": "cancel", "method": "POST" }, { "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/suspend", "rel": "suspend", "method": "POST" }, { "href": "https://api-m.paypal.com/v1/billing/subscriptions/I-BW452GLLEP1G/capture", "rel": "capture", "method": "POST" } ] } } } } } }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.revise-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/subscriptions.revise-404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/subscriptions.revise-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_revise_request" }, "examples": { "subscription_revise_request": { "value": { "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" } } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } }, "/v1/billing/subscriptions/{id}/suspend": { "post": { "summary": "Suspend subscription", "description": "Suspends the subscription.", "operationId": "subscriptions.suspend", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.suspend-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/subscriptions.suspend-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_suspend_request" }, "examples": { "subscription_suspend_request": { "value": { "reason": "Item out of stock" } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } }, "/v1/billing/subscriptions/{id}/cancel": { "post": { "summary": "Cancel subscription", "description": "Cancels the subscription.", "operationId": "subscriptions.cancel", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.cancel-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/subscriptions.cancel-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_cancel_request" }, "examples": { "subscription_cancel_request": { "value": { "reason": "Not satisfied with the service" } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } }, "/v1/billing/subscriptions/{id}/activate": { "post": { "summary": "Activate subscription", "description": "Activates the subscription.", "operationId": "subscriptions.activate", "responses": { "204": { "description": "A successful request returns the HTTP `204 No Content` status code with no JSON response body." }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.activate-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/subscriptions.activate-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_activate_request" }, "examples": { "subscription_activate_request": { "value": { "reason": "Reactivating the subscription" } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } }, "/v1/billing/subscriptions/{id}/capture": { "post": { "summary": "Capture authorized payment on subscription", "description": "Captures an authorized payment from the subscriber on the subscription.", "operationId": "subscriptions.capture", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transaction" } } } }, "202": { "description": "Request Accepted." }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.capture-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "422": { "description": "The requested action could not be performed, semantically incorrect, or failed business validation.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/subscriptions.capture-422" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/paypal_request_id" }, { "$ref": "#/components/parameters/id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription_capture_request" }, "examples": { "subscription_capture_request": { "value": { "note": "Charging as the balance reached the limit", "capture_type": "OUTSTANDING_BALANCE", "amount": { "currency_code": "USD", "value": "100" } } } } } } }, "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } }, "/v1/billing/subscriptions/{id}/transactions": { "get": { "summary": "List transactions for subscription", "description": "Lists transactions for a subscription.", "operationId": "subscriptions.transactions", "responses": { "200": { "description": "A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/transactions_list" } } } }, "400": { "description": "Bad Request. Request is not well-formed, syntactically incorrect, or violates schema.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/subscriptions.transactions-400" } ] } } } }, "401": { "description": "Authentication failed due to missing authorization header, or invalid authentication credentials.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/401" } ] } } } }, "403": { "description": "Authorization failed due to insufficient permissions.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/403" } ] } } } }, "404": { "description": "The specified resource does not exist.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/404" } ] } } } }, "500": { "description": "An internal server error has occurred.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_500" } } } }, "default": { "$ref": "#/components/responses/default" } }, "parameters": [ { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/start_time" }, { "$ref": "#/components/parameters/end_time" } ], "security": [ { "Oauth2": [ "https://uri.paypal.com/services/subscriptions" ] } ], "tags": [ "subscriptions" ] } } }, "components": { "requestBodies": { "patch_request": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/patch_request" } } } } }, "securitySchemes": { "Oauth2": { "type": "oauth2", "description": "Oauth 2.0 authentication", "flows": { "clientCredentials": { "tokenUrl": "/v1/oauth2/token", "scopes": { "https://uri.paypal.com/services/subscriptions": "Manage plan & subscription" } } } } }, "responses": { "default": { "description": "The default response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error_default" } } } } }, "schemas": { "400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } } ] } } } }, "401": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_ACCOUNT_STATUS", "properties": { "issue": { "type": "string", "enum": [ "INVALID_ACCOUNT_STATUS" ] }, "description": { "type": "string", "enum": [ "Account validations failed for the user." ] } } } ] } } } }, "403": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "PERMISSION_DENIED", "properties": { "issue": { "type": "string", "enum": [ "PERMISSION_DENIED" ] }, "description": { "type": "string", "enum": [ "You do not have permission to access or perform operations on this resource." ] } } } ] } } } }, "404": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_RESOURCE_ID", "properties": { "issue": { "type": "string", "enum": [ "INVALID_RESOURCE_ID" ] }, "description": { "type": "string", "enum": [ "Specified resource ID does not exist. Please check the resource ID and try again." ] } } } ] } } } }, "422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "CURRENCY_MISMATCH", "properties": { "issue": { "type": "string", "enum": [ "CURRENCY_MISMATCH" ] }, "description": { "type": "string", "enum": [ "All currency codes in the request should be of similar value." ] } } }, { "title": "MULTIPLE_FREE_TRIAL_BILLING_CYCLES_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "MULTIPLE_FREE_TRIAL_BILLING_CYCLES_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Only one free trial billing cycle is allowed." ] } } }, { "title": "MORE_THAN_TWO_TRIAL_BILLING_CYCLE_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "MORE_THAN_TWO_TRIAL_BILLING_CYCLE_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Only two trial billing cycles are allowed." ] } } }, { "title": "MISSING_REGULAR_BILLING_CYCLE", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REGULAR_BILLING_CYCLE" ] }, "description": { "type": "string", "enum": [ "Plan should have at least one regular billing cycle." ] } } }, { "title": "MULTIPLE_REGULAR_BILLING_CYCLES_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "MULTIPLE_REGULAR_BILLING_CYCLES_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Only one regular billing cycle is allowed." ] } } }, { "title": "INVALID_BILLING_CYCLE_SEQUENCE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_BILLING_CYCLE_SEQUENCE" ] }, "description": { "type": "string", "enum": [ "Billing cycle sequence should start with `1` and be consecutive." ] } } }, { "title": "INVALID_BILLING_CYCLE_SEQUENCE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_BILLING_CYCLE_SEQUENCE" ] }, "description": { "type": "string", "enum": [ "Trial Billing cycle should precede regular billing cycle." ] } } }, { "title": "INVALID_TRIAL_BILLING_TOTAL_CYCLES", "properties": { "issue": { "type": "string", "enum": [ "INVALID_TRIAL_BILLING_TOTAL_CYCLES" ] }, "description": { "type": "string", "enum": [ "Total cycles for trial billing must be greater than '0'." ] } } }, { "title": "INVALID_PRICING_TIER_AMOUNT", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_AMOUNT" ] }, "description": { "type": "string", "enum": [ "Free tiers are not supported." ] } } }, { "title": "MISSING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "MISSING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "Tier(s) are missing for some quantities." ] } } }, { "title": "OVERLAPPING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "OVERLAPPING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "The specified quantity overlaps with multiple pricing tiers." ] } } }, { "title": "INVALID_PRICING_MODEL", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_MODEL" ] }, "description": { "type": "string", "enum": [ "The specified pricing model is not supported for trial billing cycle." ] } } }, { "title": "FIXED_PRICE_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "FIXED_PRICE_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Fixed price is not supported for tiered pricing schemes." ] } } }, { "title": "INVALID_PRICING_TIER_QUANTITY", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_QUANTITY" ] }, "description": { "type": "string", "enum": [ "Tier starting quantity must be less than ending quantity." ] } } }, { "title": "INVALID_QUANTITY_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "INVALID_QUANTITY_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Quantity is always supported for volume and tiered plans." ] } } }, { "title": "CURRENCY_NOT_SUPPORTED_FOR_RECEIVER", "properties": { "issue": { "type": "string", "enum": [ "CURRENCY_NOT_SUPPORTED_FOR_RECEIVER" ] }, "description": { "type": "string", "enum": [ "This currency cannot be accepted for this recipient’s account." ] } } }, { "title": "INVALID_METADATA_CUSTOM_NOTE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_METADATA_CUSTOM_NOTE" ] }, "description": { "type": "string", "enum": [ "Merchant custom note cannot exceed 255 characters." ] } } }, { "title": "INVALID_METADATA_INVOICE_ID", "properties": { "issue": { "type": "string", "enum": [ "INVALID_METADATA_INVOICE_ID" ] }, "description": { "type": "string", "enum": [ "Invoice id cannot exceed 127 characters." ] } } } ] } } } }, "error_details": { "title": "Error Details", "type": "object", "description": "The error details. Required for client-side `4XX` errors.", "properties": { "field": { "type": "string", "description": "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": { "type": "string", "description": "The value of the field that caused the error." }, "location": { "$ref": "#/components/schemas/error_location" }, "issue": { "type": "string", "description": "The unique, fine-grained application-level error code." }, "description": { "type": "string", "description": "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." } }, "required": [ "issue" ] }, "error_location": { "type": "string", "description": "The location of the field that caused the error. Value is `body`, `path`, or `query`.", "enum": [ "body", "path", "query" ], "default": "body" }, "error_default": { "description": "The default error response.", "oneOf": [ { "$ref": "#/components/schemas/error_400" }, { "$ref": "#/components/schemas/error_401" }, { "$ref": "#/components/schemas/error_403" }, { "$ref": "#/components/schemas/error_404" }, { "$ref": "#/components/schemas/error_409" }, { "$ref": "#/components/schemas/error_415" }, { "$ref": "#/components/schemas/error_422" }, { "$ref": "#/components/schemas/error_500" }, { "$ref": "#/components/schemas/error_503" } ] }, "error_link_description": { "title": "Link Description", "description": "The request-related [HATEOAS link](/api/rest/responses/#hateoas-links) information.", "type": "object", "required": [ "href", "rel" ], "properties": { "href": { "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.", "type": "string", "minLength": 0, "maxLength": 20000, "pattern": "^.*$" }, "rel": { "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).", "type": "string", "minLength": 0, "maxLength": 100, "pattern": "^.*$" }, "method": { "description": "The HTTP method required to make the related call.", "type": "string", "minLength": 3, "maxLength": 6, "pattern": "^[A-Z]*$", "enum": [ "GET", "POST", "PUT", "DELETE", "PATCH" ] } } }, "error_400": { "type": "object", "title": "Bad Request Error", "description": "Request is not well-formed, syntactically incorrect, or violates schema.", "properties": { "name": { "type": "string", "enum": [ "INVALID_REQUEST" ] }, "message": { "type": "string", "enum": [ "Request is not well-formed, syntactically incorrect, or violates schema." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_401": { "type": "object", "title": "Unauthorized Error", "description": "Authentication failed due to missing Authorization header, or invalid authentication credentials.", "properties": { "name": { "type": "string", "enum": [ "AUTHENTICATION_FAILURE" ] }, "message": { "type": "string", "enum": [ "Authentication failed due to missing authorization header, or invalid authentication credentials." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_403": { "type": "object", "title": "Not Authorized Error", "description": "The client is not authorized to access this resource, although it may have valid credentials. ", "properties": { "name": { "type": "string", "enum": [ "NOT_AUTHORIZED" ] }, "message": { "type": "string", "enum": [ "Authorization failed due to insufficient permissions." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_404": { "type": "object", "title": "Not found Error", "description": "The server has not found anything matching the request URI. This either means that the URI is incorrect or the resource is not available.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_NOT_FOUND" ] }, "message": { "type": "string", "enum": [ "The specified resource does not exist." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_409": { "type": "object", "title": "Resource Conflict Error", "description": "The server has detected a conflict while processing this request.", "properties": { "name": { "type": "string", "enum": [ "RESOURCE_CONFLICT" ] }, "message": { "type": "string", "enum": [ "The server has detected a conflict while processing this request." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_415": { "type": "object", "title": "Unsupported Media Type Error", "description": "The server does not support the request payload's media type.", "properties": { "name": { "type": "string", "enum": [ "UNSUPPORTED_MEDIA_TYPE" ] }, "message": { "type": "string", "enum": [ "The server does not support the request payload's media type." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_422": { "type": "object", "title": "Unprocessable Entity Error", "description": "The requested action cannot be performed and may require interaction with APIs or processes outside of the current request. This is distinct from a 500 response in that there are no systemic problems limiting the API from performing the request.", "properties": { "name": { "type": "string", "enum": [ "UNPROCESSABLE_ENTITY" ] }, "message": { "type": "string", "enum": [ "The requested action could not be performed, semantically incorrect, or failed business validation." ] }, "details": { "type": "array", "items": { "$ref": "#/components/schemas/error_details" } }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } } }, "error_500": { "type": "object", "title": "Internal Server Error", "description": "This is either a system or application error, and generally indicates that although the client appeared to provide a correct request, something unexpected has gone wrong on the server.", "properties": { "name": { "type": "string", "enum": [ "INTERNAL_SERVER_ERROR" ] }, "message": { "type": "string", "enum": [ "An internal server error occurred." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "INTERNAL_SERVER_ERROR", "message": "An internal server error occurred.", "debug_id": "90957fca61718", "links": [ { "href": "https://developer.paypal.com/api/orders/v2/#error-INTERNAL_SERVER_ERROR", "rel": "information_link" } ] } }, "error_503": { "type": "object", "title": "Service Unavailable Error", "description": "The server is temporarily unable to handle the request, for example, because of planned maintenance or downtime.", "properties": { "name": { "type": "string", "enum": [ "SERVICE_UNAVAILABLE" ] }, "message": { "type": "string", "enum": [ "Service Unavailable." ] }, "debug_id": { "type": "string", "description": "The PayPal internal ID. Used for correlation purposes." }, "links": { "description": "An array of request-related [HATEOAS links](https://en.wikipedia.org/wiki/HATEOAS).", "type": "array", "minItems": 0, "maxItems": 10000, "items": { "$ref": "#/components/schemas/error_link_description" } } }, "example": { "name": "SERVICE_UNAVAILABLE", "message": "Service Unavailable.", "debug_id": "90957fca61718", "information_link": "https://developer.paypal.com/docs/api/orders/v2/#error-SERVICE_UNAVAILABLE" } }, "currency_code": { "description": "The [three-character ISO-4217 currency code](/docs/integration/direct/rest/currency-codes/) that identifies the currency.", "type": "string", "format": "ppaas_common_currency_code_v2", "minLength": 3, "maxLength": 3 }, "money": { "type": "object", "title": "Money", "description": "The currency and amount for a financial transaction, such as a balance or payment due.", "properties": { "currency_code": { "$ref": "#/components/schemas/currency_code" }, "value": { "type": "string", "description": "The value, which might be:For the required number of decimal places for a currency code, see [Currency Codes](/docs/integration/direct/rest/currency-codes/).", "maxLength": 32, "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" } }, "required": [ "currency_code", "value" ] }, "pricing_tier": { "title": "Pricing Tier", "description": "The pricing tier details.", "type": "object", "properties": { "starting_quantity": { "type": "string", "description": "The starting quantity for the tier.", "pattern": "^([0-9]+|([0-9]+)?[.][0-9]+)$", "minLength": 1, "maxLength": 32 }, "ending_quantity": { "type": "string", "description": "The ending quantity for the tier. Optional for the last tier.", "pattern": "^([0-9]+|([0-9]+)?[.][0-9]+)$", "minLength": 1, "maxLength": 32 }, "amount": { "description": "The pricing amount for the tier.", "$ref": "#/components/schemas/money" } }, "required": [ "starting_quantity", "amount" ] }, "date_time": { "type": "string", "description": "The date and time, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). Seconds are required while fractional seconds are optional.
Note: The regular expression provides guidance but does not reject all invalid dates.
", "format": "ppaas_date_time_v3", "minLength": 20, "maxLength": 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_scheme": { "title": "Pricing Scheme", "description": "The pricing scheme details.", "type": "object", "properties": { "version": { "type": "integer", "description": "The version of the pricing scheme.", "minimum": 0, "maximum": 999, "readOnly": true }, "fixed_price": { "description": "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.", "$ref": "#/components/schemas/money" }, "pricing_model": { "type": "string", "description": "The pricing model for tiered plan. The `tiers` parameter is required.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "enum": [ "VOLUME", "TIERED" ] }, "tiers": { "type": "array", "description": "An array of pricing tiers which are used for billing volume/tiered plans. pricing_model field has to be specified.", "minItems": 1, "maxItems": 32, "items": { "$ref": "#/components/schemas/pricing_tier" } }, "create_time": { "description": "The date and time when this pricing scheme was created, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" }, "update_time": { "description": "The date and time when this pricing scheme was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" } } }, "frequency": { "title": "Billing Cycle Frequency", "description": "The frequency of the billing cycle.", "type": "object", "properties": { "interval_unit": { "type": "string", "description": "The interval at which the subscription is charged or billed.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "enum": [ "DAY", "WEEK", "MONTH", "YEAR" ] }, "interval_count": { "type": "integer", "description": "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": 1, "maximum": 365, "default": 1 } }, "required": [ "interval_unit" ] }, "billing_cycle": { "title": "Billing Cycle", "description": "The billing cycle details.", "type": "object", "properties": { "pricing_scheme": { "description": "The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.", "$ref": "#/components/schemas/pricing_scheme" }, "frequency": { "description": "The frequency details for this billing cycle.", "$ref": "#/components/schemas/frequency" }, "tenure_type": { "type": "string", "description": "The tenure type of the billing cycle. In case of a plan having trial cycle, only 2 trial cycles are allowed per plan.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "enum": [ "REGULAR", "TRIAL" ] }, "sequence": { "type": "integer", "description": "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": 1, "maximum": 99 }, "total_cycles": { "type": "integer", "description": "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).", "minimum": 0, "maximum": 999, "default": 1 } }, "required": [ "frequency", "tenure_type", "sequence" ] }, "payment_preferences": { "title": "Payment Preferences", "description": "The payment preferences for a subscription.", "type": "object", "properties": { "auto_bill_outstanding": { "type": "boolean", "description": "Indicates whether to automatically bill the outstanding amount in the next billing cycle.", "default": true }, "setup_fee": { "description": "The initial set-up fee for the service.", "$ref": "#/components/schemas/money" }, "setup_fee_failure_action": { "type": "string", "description": "The action to take on the subscription if the initial payment for the setup fails.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "default": "CANCEL", "enum": [ "CONTINUE", "CANCEL" ] }, "payment_failure_threshold": { "type": "integer", "description": "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.", "minimum": 0, "maximum": 999, "default": 0 } } }, "percentage": { "type": "string", "description": "The percentage, as a fixed-point, signed decimal number. For example, define a 19.99% interest rate as `19.99`.", "format": "ppaas_common_percentage_v2", "pattern": "^((-?[0-9]+)|(-?([0-9]+)?[.][0-9]+))$" }, "taxes": { "title": "Taxes", "description": "The tax details.", "type": "object", "properties": { "percentage": { "description": "The tax percentage on the billing amount.", "$ref": "#/components/schemas/percentage" }, "inclusive": { "type": "boolean", "description": "Indicates whether the tax was already included in the billing amount.", "default": true } }, "required": [ "percentage" ] }, "link_description": { "type": "object", "title": "Link Description", "description": "The request-related [HATEOAS link](/docs/api/reference/api-responses/#hateoas-links) information.", "required": [ "href", "rel" ], "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." }, "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)." }, "method": { "type": "string", "description": "The HTTP method required to make the related call.", "enum": [ "GET", "POST", "PUT", "DELETE", "HEAD", "CONNECT", "OPTIONS", "PATCH" ] } } }, "plan": { "title": "Plan", "description": "The plan details.", "type": "object", "properties": { "id": { "type": "string", "description": "The unique PayPal-generated ID for the plan.", "minLength": 3, "maxLength": 50, "readOnly": true }, "product_id": { "type": "string", "description": "The ID for the product.", "minLength": 6, "maxLength": 50 }, "name": { "type": "string", "description": "The plan name.", "minLength": 1, "maxLength": 127 }, "status": { "type": "string", "description": "The plan status.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "enum": [ "CREATED", "INACTIVE", "ACTIVE" ] }, "description": { "type": "string", "description": "The detailed description of the plan.", "minLength": 1, "maxLength": 127 }, "billing_cycles": { "type": "array", "description": "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.", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/billing_cycle" } }, "payment_preferences": { "$ref": "#/components/schemas/payment_preferences" }, "taxes": { "$ref": "#/components/schemas/taxes" }, "quantity_supported": { "type": "boolean", "description": "Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.", "default": false }, "create_time": { "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, "$ref": "#/components/schemas/date_time" }, "update_time": { "description": "The date and time when the plan was last updated, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" }, "links": { "type": "array", "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "readOnly": true, "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/link_description", "readOnly": true } } } }, "plan_collection": { "title": "Plan Collection", "description": "The list of plans with details.", "type": "object", "properties": { "plans": { "type": "array", "minItems": 0, "maxItems": 32767, "description": "An array of plans.", "items": { "$ref": "#/components/schemas/plan" } }, "total_items": { "type": "integer", "description": "The total number of items.", "minimum": 0, "maximum": 500000000 }, "total_pages": { "type": "integer", "description": "The total number of pages.", "minimum": 0, "maximum": 100000000 }, "links": { "type": "array", "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "readOnly": true, "minItems": 1, "maxItems": 10, "items": { "readOnly": true, "$ref": "#/components/schemas/link_description" } } } }, "plan_request_POST": { "title": "Create Plan Request", "description": "The create plan request details.", "type": "object", "properties": { "product_id": { "type": "string", "description": "The ID of the product created through Catalog Products API.", "minLength": 6, "maxLength": 50 }, "name": { "type": "string", "description": "The plan name.", "minLength": 1, "maxLength": 127 }, "status": { "type": "string", "description": "The initial state of the plan. Allowed input values are CREATED and ACTIVE.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "default": "ACTIVE", "enum": [ "CREATED", "INACTIVE", "ACTIVE" ] }, "description": { "type": "string", "description": "The detailed description of the plan.", "minLength": 1, "maxLength": 127 }, "billing_cycles": { "type": "array", "description": "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.", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/billing_cycle" } }, "payment_preferences": { "$ref": "#/components/schemas/payment_preferences" }, "taxes": { "$ref": "#/components/schemas/taxes" }, "quantity_supported": { "type": "boolean", "description": "Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.", "default": false } }, "required": [ "name", "billing_cycles", "payment_preferences", "product_id" ] }, "plans.create-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "The value of a field does not conform to the expected format." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "A required field is missing." ] } } }, { "title": "INVALID_STRING_MIN_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MIN_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too short." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } }, { "title": "INVALID_INTEGER_MIN_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MIN_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too small." ] } } }, { "title": "INVALID_INTEGER_MAX_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MAX_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too large." ] } } } ] } } } }, "patch": { "type": "object", "title": "Patch", "description": "The JSON patch object to apply partial updates to resources.", "properties": { "op": { "type": "string", "description": "The operation.", "enum": [ "add", "remove", "replace", "move", "copy", "test" ] }, "path": { "type": "string", "description": "The JSON Pointer to the target document location at which to complete the operation." }, "value": { "title": "Patch Value", "description": "The value to apply. The remove operation does not require a value." }, "from": { "type": "string", "description": "The JSON Pointer to the target document location from which to move the value. Required for the move operation." } }, "required": [ "op" ] }, "patch_request": { "type": "array", "title": "Patch Request", "description": "An array of JSON patch objects to apply partial updates to resources.", "items": { "$ref": "#/components/schemas/patch" } }, "plans.patch-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "UNSUPPORTED_PATCH_OPERATION", "properties": { "issue": { "type": "string", "enum": [ "UNSUPPORTED_PATCH_OPERATION" ] }, "description": { "type": "string", "enum": [ "The specified patch operation not supported for this field." ] } } }, { "title": "INVALID_PATCH_PATH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PATCH_PATH" ] }, "description": { "type": "string", "enum": [ "The specified field cannot be patched." ] } } }, { "title": "INVALID_PATCH_PATH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PATCH_PATH" ] }, "description": { "type": "string", "enum": [ "Multiple operations on the same field are not allowed." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "The value of a field does not conform to the expected format." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The field is not eligible for '$value' patch operation." ] } } } ] } } } }, "plans.patch-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "PLAN_STATUS_INACTIVE", "properties": { "issue": { "type": "string", "enum": [ "PLAN_STATUS_INACTIVE" ] }, "description": { "type": "string", "enum": [ "Status update is the only patchable filed on an inactive plan." ] } } } ] } } } }, "plans.activate-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "PLAN_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "PLAN_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid plan status for activate action; plan status should be either created or inactive." ] } } } ] } } } }, "plans.deactivate-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "PLAN_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "PLAN_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid plan status for deactivate action; plan status should be active." ] } } } ] } } } }, "update_pricing_scheme_request": { "title": "Update Pricing Scheme", "description": "The update pricing scheme request details.", "type": "object", "properties": { "billing_cycle_sequence": { "type": "integer", "description": "The billing cycle sequence.", "minimum": 1, "maximum": 99 }, "pricing_scheme": { "$ref": "#/components/schemas/pricing_scheme" } }, "required": [ "billing_cycle_sequence", "pricing_scheme" ] }, "update_pricing_schemes_list_request": { "title": "Update Pricing Scheme Request", "description": "The update pricing scheme request details.", "type": "object", "properties": { "pricing_schemes": { "type": "array", "description": "An array of pricing schemes.", "minItems": 1, "maxItems": 99, "items": { "$ref": "#/components/schemas/update_pricing_scheme_request" } } }, "required": [ "pricing_schemes" ] }, "plans.update-pricing-schemes-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "A required field is missing." ] } } } ] } } } }, "plans.update-pricing-schemes-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "CURRENCY_MISMATCH", "properties": { "issue": { "type": "string", "enum": [ "CURRENCY_MISMATCH" ] }, "description": { "type": "string", "enum": [ "The currency code is different from the plan's currency code." ] } } }, { "title": "INVALID_BILLING_CYCLE_SEQUENCE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_BILLING_CYCLE_SEQUENCE" ] }, "description": { "type": "string", "enum": [ "The provided billing cycle sequence is not available." ] } } }, { "title": "INVALID_PRICING_SCHEME", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_SCHEME" ] }, "description": { "type": "string", "enum": [ "The new pricing scheme should be of the same type as that of the old one." ] } } }, { "title": "INVALID_PRICING_TIER_AMOUNT", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_AMOUNT" ] }, "description": { "type": "string", "enum": [ "Free tiers are not supported." ] } } }, { "title": "MISSING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "MISSING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "Tier(s) are missing for some quantities." ] } } }, { "title": "OVERLAPPING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "OVERLAPPING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "The specified quantity overlaps with multiple pricing tiers." ] } } }, { "title": "INVALID_PRICING_MODEL", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_MODEL" ] }, "description": { "type": "string", "enum": [ "The specified pricing model is not supported for trial billing cycle." ] } } }, { "title": "FIXED_PRICE_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "FIXED_PRICE_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Fixed price is not supported for tiered pricing schemes." ] } } }, { "title": "INVALID_PRICING_TIER_QUANTITY", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_QUANTITY" ] }, "description": { "type": "string", "enum": [ "Tier starting quantity must be less than ending quantity." ] } } }, { "title": "PRICING_SCHEME_UPDATE_NOT_ALLOWED", "properties": { "issue": { "type": "string", "enum": [ "PRICING_SCHEME_UPDATE_NOT_ALLOWED" ] }, "description": { "type": "string", "enum": [ "Pricing scheme update is not allowed for the plan." ] } } } ] } } } }, "email": { "type": "string", "description": "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.
", "format": "merchant_common_email_address_v2", "maxLength": 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])+)\\])" }, "account_id": { "type": "string", "title": "PayPal Account Identifier", "description": "The account identifier for a PayPal account.", "format": "ppaas_payer_id_v3", "minLength": 13, "maxLength": 13, "pattern": "^[2-9A-HJ-NP-Z]{13}$" }, "payer_base": { "type": "object", "title": "Payer Base", "description": "The customer who approves and pays for the order. The customer is also known as the payer.", "properties": { "email_address": { "description": "The email address of the payer.", "$ref": "#/components/schemas/email" }, "payer_id": { "description": "The PayPal-assigned ID for the payer.", "readOnly": true, "$ref": "#/components/schemas/account_id" } } }, "name": { "type": "object", "title": "Name", "description": "The name of the party.", "properties": { "prefix": { "type": "string", "description": "The prefix, or title, to the party's name.", "maxLength": 140 }, "given_name": { "type": "string", "description": "When the party is a person, the party's given, or first, name.", "maxLength": 140 }, "surname": { "type": "string", "description": "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.", "maxLength": 140 }, "middle_name": { "type": "string", "description": "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.", "maxLength": 140 }, "suffix": { "type": "string", "description": "The suffix for the party's name.", "maxLength": 140 }, "alternate_full_name": { "type": "string", "description": "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.", "maxLength": 300 }, "full_name": { "type": "string", "description": "When the party is a person, the party's full name.", "maxLength": 300 } } }, "phone_type": { "type": "string", "title": "Phone Type", "description": "The phone type.", "enum": [ "FAX", "HOME", "MOBILE", "OTHER", "PAGER" ] }, "phone": { "type": "object", "title": "Phone", "description": "The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en).", "properties": { "country_code": { "type": "string", "description": "The country calling code (CC), in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). 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).", "minLength": 1, "maxLength": 3, "pattern": "^[0-9]{1,3}?$" }, "national_number": { "type": "string", "description": "The national number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). 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).", "minLength": 1, "maxLength": 14, "pattern": "^[0-9]{1,14}?$" }, "extension_number": { "type": "string", "description": "The extension number.", "minLength": 1, "maxLength": 15, "pattern": "^[0-9]{1,15}?$" } }, "required": [ "country_code", "national_number" ] }, "phone_with_type": { "type": "object", "title": "Phone With Type", "description": "The phone information.", "properties": { "phone_type": { "$ref": "#/components/schemas/phone_type" }, "phone_number": { "description": "The phone number, in its canonical international [E.164 numbering plan format](https://www.itu.int/rec/T-REC-E.164/en). Supports only the `national_number` property.", "$ref": "#/components/schemas/phone" } }, "required": [ "phone_number" ] }, "date_no_time": { "type": "string", "description": "The stand-alone date, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6). 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.", "format": "ppaas_date_notime_v2", "minLength": 10, "maxLength": 10, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[1-2][0-9]|3[0-1])$" }, "tax_info": { "type": "object", "description": "The tax ID of the customer. The customer is also known as the payer. Both `tax_id` and `tax_id_type` are required.", "title": "Tax Information", "properties": { "tax_id": { "type": "string", "description": "The customer's tax ID value.", "maxLength": 14 }, "tax_id_type": { "type": "string", "description": "The customer's tax ID type.", "enum": [ "BR_CPF", "BR_CNPJ" ] } }, "required": [ "tax_id", "tax_id_type" ] }, "country_code": { "type": "string", "description": "The [two-character ISO 3166-1 code](/docs/integration/direct/rest/country-codes/) 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.
", "format": "ppaas_common_country_code_v2", "maxLength": 2, "minLength": 2, "pattern": "^([A-Z]{2}|C2)$" }, "address_portable": { "type": "object", "title": "Portable Postal Address (Medium-Grained)", "description": "The portable international postal address. Maps to [AddressValidationMetadata](https://github.com/googlei18n/libaddressinput/wiki/AddressValidationMetadata) and HTML 5.1 [Autofilling form controls: the autocomplete attribute](https://www.w3.org/TR/html51/sec-forms.html#autofilling-form-controls-the-autocomplete-attribute).", "properties": { "address_line_1": { "type": "string", "description": "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.", "maxLength": 300 }, "address_line_2": { "type": "string", "description": "The second line of the address. For example, suite or apartment number.", "maxLength": 300 }, "address_line_3": { "type": "string", "description": "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.", "maxLength": 100 }, "admin_area_4": { "type": "string", "description": "The neighborhood, ward, or district. Smaller than `admin_area_level_3` or `sub_locality`. Value is:", "maxLength": 100 }, "admin_area_3": { "type": "string", "description": "A sub-locality, suburb, neighborhood, or district. Smaller than `admin_area_level_2`. Value is:", "maxLength": 100 }, "admin_area_2": { "type": "string", "description": "A city, town, or village. Smaller than `admin_area_level_1`.", "maxLength": 120 }, "admin_area_1": { "type": "string", "description": "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:", "maxLength": 300 }, "postal_code": { "type": "string", "description": "The postal code, which is the zip code or equivalent. Typically required for countries with a postal code or an equivalent. See [postal code](https://en.wikipedia.org/wiki/Postal_code).", "maxLength": 60 }, "country_code": { "$ref": "#/components/schemas/country_code" }, "address_details": { "type": "object", "title": "Address Details", "description": "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`.", "properties": { "street_number": { "type": "string", "description": "The street number.", "maxLength": 100 }, "street_name": { "type": "string", "description": "The street name. Just `Drury` in `Drury Lane`.", "maxLength": 100 }, "street_type": { "type": "string", "description": "The street type. For example, avenue, boulevard, road, or expressway.", "maxLength": 100 }, "delivery_service": { "type": "string", "description": "The delivery service. Post office box, bag number, or post office name.", "maxLength": 100 }, "building_name": { "type": "string", "description": "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.", "maxLength": 100 }, "sub_building": { "type": "string", "description": "The first-order entity below a named building or location that represents the sub-premises. Usually a single building within a collection of buildings with a common name. Can be a flat, story, floor, room, or apartment.", "maxLength": 100 } } } }, "required": [ "country_code" ] }, "payer": { "type": "object", "title": "Customer", "description": "The customer who approves and pays for the order. The customer is also known as the payer.", "format": "payer_v1", "allOf": [ { "$ref": "#/components/schemas/payer_base" }, { "properties": { "name": { "description": "The name of the payer. Supports only the `given_name` and `surname` properties.", "$ref": "#/components/schemas/name" }, "phone": { "description": "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`.", "$ref": "#/components/schemas/phone_with_type" }, "birth_date": { "description": "The birth date of the payer in `YYYY-MM-DD` format.", "$ref": "#/components/schemas/date_no_time" }, "tax_info": { "description": "The tax information of the payer. Required only for Brazilian payer's. Both `tax_id` and `tax_id_type` are required.", "$ref": "#/components/schemas/tax_info" }, "address": { "description": "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.", "$ref": "#/components/schemas/address_portable" } } } ] }, "shipping_detail": { "type": "object", "description": "The shipping details.", "title": "Shipping Details", "properties": { "name": { "description": "The name of the person to whom to ship the items. Supports only the `full_name` property.", "$ref": "#/components/schemas/name" }, "type": { "description": "The method by which the payer wants to get their items from the payee e.g shipping, in-person pickup. Either type or options but not both may be present.", "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "enum": [ "SHIPPING", "PICKUP_IN_PERSON" ] }, "address": { "description": "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.", "$ref": "#/components/schemas/address_portable" } } }, "date_year_month": { "type": "string", "description": "The year and month, in ISO-8601 `YYYY-MM` date format. See [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "minLength": 7, "maxLength": 7, "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$" }, "card_brand": { "type": "string", "title": "Card Brand", "description": "The card network or brand. Applies to credit, debit, gift, and payment cards.", "minLength": 1, "maxLength": 255, "pattern": "^[A-Z_]+$", "enum": [ "VISA", "MASTERCARD", "DISCOVER", "AMEX", "SOLO", "JCB", "STAR", "DELTA", "SWITCH", "MAESTRO", "CB_NATIONALE", "CONFIGOGA", "CONFIDIS", "ELECTRON", "CETELEM", "CHINA_UNION_PAY" ] }, "card": { "type": "object", "title": "Card", "description": "The payment card to use to fund a payment. Can be a credit or debit card.", "properties": { "id": { "type": "string", "description": "The PayPal-generated ID for the card.", "readOnly": true }, "name": { "type": "string", "description": "The card holder's name as it appears on the card.", "maxLength": 300 }, "number": { "type": "string", "description": "The primary account number (PAN) for the payment card.", "minLength": 13, "maxLength": 19 }, "expiry": { "description": "The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_year_month" }, "security_code": { "type": "string", "description": "The three- or four-digit security code of the card. Also known as the CVV, CVC, CVN, CVE, or CID. This parameter cannot be present in the request when `payment_initiator=MERCHANT`.", "pattern": "[0-9]{3,4}" }, "last_digits": { "type": "string", "description": "The last digits of the payment card.", "pattern": "[0-9]{2,}", "readOnly": true }, "card_type": { "description": "The card brand or network. Typically used in the response.", "readOnly": true, "$ref": "#/components/schemas/card_brand" }, "billing_address": { "description": "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.", "$ref": "#/components/schemas/address_portable" } }, "required": [ "number", "expiry" ] }, "payment_source": { "type": "object", "title": "Payment Source", "description": "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.", "properties": { "card": { "$ref": "#/components/schemas/card" } } }, "subscriber_request": { "title": "Subscriber Request Information", "description": "The subscriber request information .", "type": "object", "allOf": [ { "$ref": "#/components/schemas/payer" }, { "properties": { "shipping_address": { "$ref": "#/components/schemas/shipping_detail" }, "payment_source": { "$ref": "#/components/schemas/payment_source" } } } ] }, "language": { "type": "string", "description": "The [language tag](https://tools.ietf.org/html/bcp47#section-2) for the language in which to localize the error-related strings, such as messages, issues, and suggested actions. The tag is made up of the [ISO 639-2 language code](https://www.loc.gov/standards/iso639-2/php/code_list.php), the optional [ISO-15924 script tag](https://www.unicode.org/iso15924/codelists.html), and the [ISO-3166 alpha-2 country code](/docs/integration/direct/rest/country-codes/).", "format": "ppaas_common_language_v3", "maxLength": 10, "minLength": 2, "pattern": "^[a-z]{2}(?:-[A-Z][a-z]{3})?(?:-(?:[A-Z]{2}))?$" }, "payee_payment_method_preference": { "type": "string", "description": "The merchant-preferred payment methods.", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "default": "UNRESTRICTED", "enum": [ "UNRESTRICTED", "IMMEDIATE_PAYMENT_REQUIRED" ] }, "payment_method": { "type": "object", "description": "The customer and merchant payment preferences.", "title": "Payment Method", "properties": { "payer_selected": { "type": "string", "description": "The customer-selected payment method on the merchant site.", "minLength": 1, "pattern": "^[0-9A-Z_]+$", "default": "PAYPAL" }, "payee_preferred": { "$ref": "#/components/schemas/payee_payment_method_preference" }, "standard_entry_class_code": { "type": "string", "description": "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.", "default": "WEB", "minLength": 3, "maxLength": 255, "enum": [ "TEL", "WEB", "CCD", "PPD" ] } } }, "application_context": { "title": "Application Context", "description": "The application context, which customizes the payer experience during the subscription approval process with PayPal.", "type": "object", "properties": { "brand_name": { "type": "string", "description": "The label that overrides the business name in the PayPal account on the PayPal site.", "minLength": 1, "maxLength": 127 }, "locale": { "description": "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`.", "$ref": "#/components/schemas/language" }, "shipping_preference": { "type": "string", "description": "The location from which the shipping address is derived.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "default": "GET_FROM_FILE", "enum": [ "GET_FROM_FILE", "NO_SHIPPING", "SET_PROVIDED_ADDRESS" ] }, "user_action": { "type": "string", "description": "Configures the label name to `Continue` or `Subscribe Now` for subscription consent experience.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "default": "SUBSCRIBE_NOW", "enum": [ "CONTINUE", "SUBSCRIBE_NOW" ] }, "payment_method": { "description": "The customer and merchant payment preferences. Currently only PAYPAL payment method is supported.", "$ref": "#/components/schemas/payment_method" }, "return_url": { "type": "string", "format": "uri", "description": "The URL where the customer is redirected after the customer approves the payment.", "minLength": 10, "maxLength": 4000 }, "cancel_url": { "type": "string", "format": "uri", "description": "The URL where the customer is redirected after the customer cancels the payment.", "minLength": 10, "maxLength": 4000 } }, "required": [ "return_url", "cancel_url" ] }, "billing_cycle_override": { "title": "Billing Cycle Override", "description": "The billing cycle details to override at subscription level. The subscription billing cycle definition has to adhere to the plan billing cycle definition.", "type": "object", "properties": { "pricing_scheme": { "description": "The active pricing scheme for this billing cycle. A free trial billing cycle does not require a pricing scheme.", "$ref": "#/components/schemas/pricing_scheme" }, "sequence": { "type": "integer", "description": "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": 1, "maximum": 99 }, "total_cycles": { "type": "integer", "description": "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).", "minimum": 0, "maximum": 999 } }, "required": [ "sequence" ] }, "payment_preferences_override": { "title": "Payment Preferences Override", "description": "The payment preferences to override at subscription level.", "type": "object", "properties": { "auto_bill_outstanding": { "type": "boolean", "description": "Indicates whether to automatically bill the outstanding amount in the next billing cycle." }, "setup_fee": { "description": "The initial set-up fee for the service.", "$ref": "#/components/schemas/money" }, "setup_fee_failure_action": { "type": "string", "description": "The action to take on the subscription if the initial payment for the setup fails.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "enum": [ "CONTINUE", "CANCEL" ] }, "payment_failure_threshold": { "type": "integer", "description": "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.", "minimum": 0, "maximum": 999 } } }, "taxes_override": { "title": "Taxes Override", "description": "The tax details.", "type": "object", "properties": { "percentage": { "description": "The tax percentage on the billing amount.", "$ref": "#/components/schemas/percentage" }, "inclusive": { "type": "boolean", "description": "Indicates whether the tax was already included in the billing amount." } } }, "plan_override": { "title": "Plan Override", "description": "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.", "type": "object", "properties": { "billing_cycles": { "type": "array", "description": "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.", "minItems": 1, "maxItems": 12, "items": { "$ref": "#/components/schemas/billing_cycle_override" } }, "payment_preferences": { "$ref": "#/components/schemas/payment_preferences_override" }, "taxes": { "$ref": "#/components/schemas/taxes_override" } } }, "subscription_request_post": { "title": "Create Subscription Request", "description": "The create subscription request details.", "type": "object", "properties": { "plan_id": { "type": "string", "description": "The ID of the plan.", "minLength": 3, "maxLength": 50 }, "start_time": { "description": "The date and time when the subscription started, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "default": "Current time", "$ref": "#/components/schemas/date_time" }, "quantity": { "type": "string", "description": "The quantity of the product in the subscription.", "pattern": "^([0-9]+|([0-9]+)?[.][0-9]+)$", "minLength": 1, "maxLength": 32 }, "shipping_amount": { "description": "The shipping charges.", "$ref": "#/components/schemas/money" }, "subscriber": { "$ref": "#/components/schemas/subscriber_request" }, "auto_renewal": { "type": "boolean", "description": "DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete.", "default": false, "deprecated": true }, "application_context": { "$ref": "#/components/schemas/application_context" }, "custom_id": { "type": "string", "description": "The custom id for the subscription. Can be invoice id.", "minLength": 1, "maxLength": 127, "pattern": "^[\\x20-\\x7E]+" }, "plan": { "description": "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.", "$ref": "#/components/schemas/plan_override" } }, "required": [ "plan_id" ] }, "subscription_status": { "title": "Subscription Status", "description": "The subscription status details.", "type": "object", "properties": { "status": { "type": "string", "description": "The status of the subscription.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "enum": [ "APPROVAL_PENDING", "APPROVED", "ACTIVE", "SUSPENDED", "CANCELLED", "EXPIRED" ] }, "status_change_note": { "type": "string", "description": "The reason or notes for the status of the subscription.", "minLength": 1, "maxLength": 128 }, "status_update_time": { "readOnly": true, "$ref": "#/components/schemas/date_time" } } }, "liability_shift": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "description": "Liability shift indicator. The outcome of the issuer's authentication.", "enum": [ "YES", "NO", "POSSIBLE", "UNKNOWN" ] }, "pares_status": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "description": "Transactions status result identifier. The outcome of the issuer's authentication.", "enum": [ "Y", "N", "U", "A", "C", "R", "D", "I" ] }, "enrolled": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[0-9A-Z_]+$", "description": "Status of Authentication eligibility.", "enum": [ "Y", "N", "U", "B" ] }, "three_d_secure_authentication_response": { "type": "object", "title": "The 3D Secure Authentication Response", "description": "Results of 3D Secure Authentication.", "properties": { "authentication_status": { "description": "The outcome of the issuer's authentication.", "$ref": "#/components/schemas/pares_status" }, "enrollment_status": { "description": "Status of authentication eligibility.", "$ref": "#/components/schemas/enrolled" } } }, "authentication_response": { "type": "object", "title": "Authentication Response", "description": "Results of Authentication such as 3D Secure.", "properties": { "liability_shift": { "$ref": "#/components/schemas/liability_shift" }, "three_d_secure": { "$ref": "#/components/schemas/three_d_secure_authentication_response" } } }, "card_response": { "type": "object", "title": "Card Response", "description": "The payment card to use to fund a payment. Card can be a credit or debit card.", "properties": { "last_digits": { "type": "string", "description": "The last digits of the payment card.", "pattern": "[0-9]{2,}", "readOnly": true }, "brand": { "description": "The card brand or network. Typically used in the response.", "readOnly": true, "$ref": "#/components/schemas/card_brand" }, "type": { "type": "string", "description": "The payment card type.", "readOnly": true, "enum": [ "CREDIT", "DEBIT", "PREPAID", "UNKNOWN" ] }, "authentication_result": { "$ref": "#/components/schemas/authentication_response" } } }, "card_response_with_billing_address": { "type": "object", "title": "Card Response with billing address and name", "description": "The payment card used to fund the payment. Card can be a credit or debit card.", "allOf": [ { "$ref": "#/components/schemas/card_response" }, { "properties": { "name": { "type": "string", "description": "The card holder's name as it appears on the card.", "minLength": 2, "maxLength": 300 }, "billing_address": { "$ref": "#/components/schemas/address_portable", "description": "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." }, "expiry": { "description": "The card expiration year and month, in [Internet date format](https://tools.ietf.org/html/rfc3339#section-5.6).", "$ref": "#/components/schemas/date_year_month" }, "currency_code": { "description": "Currency code of the given instrument", "$ref": "#/components/schemas/currency_code" } } } ] }, "payment_source_response": { "type": "object", "title": "Payment Source Response", "description": "The payment source used to fund the payment.", "properties": { "card": { "$ref": "#/components/schemas/card_response_with_billing_address" } } }, "subscriber": { "title": "Subscriber Response Information", "description": "The subscriber response information.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/payer" }, { "properties": { "shipping_address": { "$ref": "#/components/schemas/shipping_detail" }, "payment_source": { "$ref": "#/components/schemas/payment_source_response" } } } ] }, "cycle_execution": { "title": "Billing Cycle Execution Details", "description": "The regular and trial execution details for a billing cycle.", "type": "object", "properties": { "tenure_type": { "type": "string", "description": "The type of the billing cycle.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "readOnly": true, "enum": [ "REGULAR", "TRIAL" ] }, "sequence": { "type": "integer", "description": "The order in which to run this cycle among other billing cycles.", "minimum": 0, "maximum": 99 }, "cycles_completed": { "type": "integer", "description": "The number of billing cycles that have completed.", "minimum": 0, "maximum": 9999, "readOnly": true }, "cycles_remaining": { "type": "integer", "description": "For a finite billing cycle, cycles_remaining is the number of remaining cycles. For an infinite billing cycle, cycles_remaining is set as 0.", "minimum": 0, "maximum": 9999, "readOnly": true }, "current_pricing_scheme_version": { "type": "integer", "description": "The active pricing scheme version for the billing cycle.", "minimum": 1, "maximum": 99, "readOnly": true }, "total_cycles": { "type": "integer", "description": "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).", "minimum": 0, "maximum": 999, "readOnly": true } }, "required": [ "tenure_type", "sequence", "cycles_completed" ] }, "last_payment_details": { "title": "Last Payment Details", "description": "The details for the last payment.", "type": "object", "allOf": [ { "properties": { "amount": { "description": "The last payment amount.", "readOnly": true, "$ref": "#/components/schemas/money" }, "time": { "description": "The date and time when the last payment was made, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" } } } ], "required": [ "amount", "time" ] }, "failed_payment_details": { "title": "Failed Payment Details", "description": "The details for the failed payment of the subscription.", "type": "object", "properties": { "amount": { "description": "The failed payment amount.", "readOnly": true, "$ref": "#/components/schemas/money" }, "time": { "description": "The date and time when the failed payment was made, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" }, "reason_code": { "type": "string", "description": "The reason code for the payment failure.", "minLength": 1, "maxLength": 120, "pattern": "^[A-Z_]+$", "readOnly": true, "enum": [ "PAYMENT_DENIED", "INTERNAL_SERVER_ERROR", "PAYEE_ACCOUNT_RESTRICTED", "PAYER_ACCOUNT_RESTRICTED", "PAYER_CANNOT_PAY", "SENDING_LIMIT_EXCEEDED", "TRANSACTION_RECEIVING_LIMIT_EXCEEDED", "CURRENCY_MISMATCH" ] }, "next_payment_retry_time": { "description": "The time when the retry attempt for the failed payment occurs, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" } }, "required": [ "amount", "time" ] }, "subscription_billing_info": { "title": "Subscription Billing Information", "description": "The billing details for the subscription. If the subscription was or is active, these fields are populated.", "type": "object", "properties": { "outstanding_balance": { "description": "The total pending bill amount, to be paid by the subscriber.", "$ref": "#/components/schemas/money" }, "cycle_executions": { "type": "array", "description": "The trial and regular billing executions.", "minItems": 0, "maxItems": 3, "items": { "$ref": "#/components/schemas/cycle_execution" }, "readOnly": true }, "last_payment": { "readOnly": true, "description": "The details for the last payment of the subscription.", "$ref": "#/components/schemas/last_payment_details" }, "next_billing_time": { "description": "The next date and time for billing this subscription, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" }, "final_payment_time": { "description": "The date and time when the final billing cycle occurs, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" }, "failed_payments_count": { "type": "integer", "description": "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.", "minimum": 0, "maximum": 999, "readOnly": true }, "last_failed_payment": { "description": "The details for the last failed payment of the subscription.", "readOnly": true, "$ref": "#/components/schemas/failed_payment_details" } }, "required": [ "outstanding_balance", "failed_payments_count" ] }, "subscription": { "title": "Subscription", "description": "The subscription details.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/subscription_status" }, { "properties": { "id": { "type": "string", "description": "The PayPal-generated ID for the subscription.", "minLength": 3, "maxLength": 50, "readOnly": true }, "plan_id": { "type": "string", "description": "The ID of the plan.", "minLength": 3, "maxLength": 50 }, "start_time": { "$ref": "#/components/schemas/date_time" }, "quantity": { "type": "string", "description": "The quantity of the product in the subscription.", "pattern": "^([0-9]+|([0-9]+)?[.][0-9]+)$", "minLength": 1, "maxLength": 32 }, "shipping_amount": { "$ref": "#/components/schemas/money" }, "subscriber": { "$ref": "#/components/schemas/subscriber" }, "billing_info": { "readOnly": true, "$ref": "#/components/schemas/subscription_billing_info" }, "create_time": { "readOnly": true, "$ref": "#/components/schemas/date_time" }, "update_time": { "readOnly": true, "$ref": "#/components/schemas/date_time" }, "custom_id": { "type": "string", "description": "The custom id for the subscription. Can be invoice id.", "minLength": 1, "maxLength": 127, "pattern": "^[\\x20-\\x7E]+" }, "plan_overridden": { "type": "boolean", "description": "Indicates whether the subscription has overridden any plan attributes.", "readOnly": true }, "plan": { "description": "Inline plan details.", "$ref": "#/components/schemas/plan" }, "links": { "type": "array", "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "readOnly": true, "items": { "readOnly": true, "$ref": "#/components/schemas/link_description" } } } } ] }, "subscriptions.create-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "The value of a field does not conform to the expected format." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "INVALID_INTEGER_MIN_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MIN_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too small." ] } } }, { "title": "INVALID_INTEGER_MAX_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MAX_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too large." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "Start time must be a valid future date and time." ] } } }, { "title": "MISSING_REQUEST_BODY", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUEST_BODY" ] }, "description": { "type": "string", "enum": [ "Request body is missing." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "A required field is missing." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } } ] } } } }, "subscriptions.create-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "PLAN_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "PLAN_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid plan status for subscription creation; plan status should be active." ] } } }, { "title": "SUBSCRIPTION_CANNOT_HAVE_QUANTITY", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_CANNOT_HAVE_QUANTITY" ] }, "description": { "type": "string", "enum": [ "Subscription can't have quantity as the plan does not support quantity." ] } } }, { "title": "CARD_SUBSCRIPTIONS_NOT_ENABLED", "properties": { "issue": { "type": "string", "enum": [ "CARD_SUBSCRIPTIONS_NOT_ENABLED" ] }, "description": { "type": "string", "enum": [ "The account is not setup to be able to process subscriptions funded by card payments. Please contact PayPal customer support." ] } } }, { "title": "3DS_CARDS_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "3DS_CARDS_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Cards that require 3DS authentication not supported." ] } } }, { "title": "INVALID_BILLING_CYCLE_SEQUENCE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_BILLING_CYCLE_SEQUENCE" ] }, "description": { "type": "string", "enum": [ "The provided billing cycle sequence is not available." ] } } }, { "title": "INVALID_PRICING_SCHEME", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_SCHEME" ] }, "description": { "type": "string", "enum": [ "The override plan pricing scheme should be of the same type as that of the original plan." ] } } }, { "title": "INVALID_PRICING_TIER_AMOUNT", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_AMOUNT" ] }, "description": { "type": "string", "enum": [ "Free tiers are not supported." ] } } }, { "title": "MISSING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "MISSING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "Tier(s) are missing for some quantities." ] } } }, { "title": "OVERLAPPING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "OVERLAPPING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "The specified quantity overlaps with multiple pricing tiers." ] } } }, { "title": "INVALID_PRICING_MODEL", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_MODEL" ] }, "description": { "type": "string", "enum": [ "The specified pricing model is not supported for trial billing cycle." ] } } }, { "title": "FIXED_PRICE_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "FIXED_PRICE_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Fixed price is not supported for tiered pricing schemes." ] } } }, { "title": "INVALID_PRICING_TIER_QUANTITY", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_QUANTITY" ] }, "description": { "type": "string", "enum": [ "Tier starting quantity must be less than ending quantity." ] } } }, { "title": "CURRENCY_MISMATCH", "properties": { "issue": { "type": "string", "enum": [ "CURRENCY_MISMATCH" ] }, "description": { "type": "string", "enum": [ "The currency code is different from the plan's currency code." ] } } } ] } } } }, "subscriptions.patch-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "UNSUPPORTED_PATCH_OPERATION", "properties": { "issue": { "type": "string", "enum": [ "UNSUPPORTED_PATCH_OPERATION" ] }, "description": { "type": "string", "enum": [ "The specified patch operation not supported for this field." ] } } }, { "title": "INVALID_PATCH_PATH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PATCH_PATH" ] }, "description": { "type": "string", "enum": [ "The specified field cannot be patched." ] } } }, { "title": "INVALID_PATCH_PATH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PATCH_PATH" ] }, "description": { "type": "string", "enum": [ "Multiple operations on the same field are not allowed." ] } } }, { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "The value of a field does not conform to the expected format." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } }, { "title": "INVALID_STRING_MIN_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MIN_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too short." ] } } }, { "title": "INVALID_INTEGER_MIN_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MIN_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too small." ] } } }, { "title": "INVALID_INTEGER_MAX_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MAX_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too large." ] } } }, { "title": "MISSING_REQUEST_BODY", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUEST_BODY" ] }, "description": { "type": "string", "enum": [ "Request body is missing." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "A required field is missing." ] } } } ] } } } }, "subscriptions.patch-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "SUBSCRIPTION_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid subscription status for patch action; subscription status should be either active or suspended." ] } } }, { "title": "CARD_SUBSCRIPTIONS_NOT_ENABLED", "properties": { "issue": { "type": "string", "enum": [ "CARD_SUBSCRIPTIONS_NOT_ENABLED" ] }, "description": { "type": "string", "enum": [ "The account is not setup to be able to process subscriptions funded by card payments. Please contact PayPal customer support." ] } } }, { "title": "3DS_CARDS_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "3DS_CARDS_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Cards that require 3DS authentication not supported." ] } } }, { "title": "BILLING_CYCLE_EXECUTION_COMPLETED", "properties": { "issue": { "type": "string", "enum": [ "BILLING_CYCLE_EXECUTION_COMPLETED" ] }, "description": { "type": "string", "enum": [ "Update cannot be performed on a billing cycle that has completed execution." ] } } }, { "title": "AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE", "properties": { "issue": { "type": "string", "enum": [ "AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE" ] }, "description": { "type": "string", "enum": [ "The new outstanding balance cannot be greater than the current outstanding balance." ] } } }, { "title": "INVALID_BILLING_TOTAL_CYCLES", "properties": { "issue": { "type": "string", "enum": [ "INVALID_BILLING_TOTAL_CYCLES" ] }, "description": { "type": "string", "enum": [ "The total cycles cannot be less than the number of billing cycles completed." ] } } }, { "title": "INVALID_PRICING_TIER_AMOUNT", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_AMOUNT" ] }, "description": { "type": "string", "enum": [ "Free tiers are not supported." ] } } }, { "title": "MISSING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "MISSING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "Tier(s) are missing for some quantities." ] } } }, { "title": "OVERLAPPING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "OVERLAPPING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "The specified quantity overlaps with multiple pricing tiers." ] } } }, { "title": "INVALID_PRICING_MODEL", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_MODEL" ] }, "description": { "type": "string", "enum": [ "The specified pricing model is not supported for trial billing cycle." ] } } }, { "title": "FIXED_PRICE_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "FIXED_PRICE_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Fixed price is not supported for tiered pricing schemes." ] } } }, { "title": "INVALID_PRICING_TIER_QUANTITY", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_QUANTITY" ] }, "description": { "type": "string", "enum": [ "Tier starting quantity must be less than ending quantity." ] } } }, { "title": "INVALID_START_TIME", "properties": { "issue": { "type": "string", "enum": [ "INVALID_START_TIME" ] }, "description": { "type": "string", "enum": [ "The start time cannot be updated for a subscription that has been activated." ] } } }, { "title": "CURRENCY_MISMATCH", "properties": { "issue": { "type": "string", "enum": [ "CURRENCY_MISMATCH" ] }, "description": { "type": "string", "enum": [ "The currency code is different from the subscription's currency code." ] } } } ] } } } }, "subscription_revise_request": { "title": "Subscription Modify Plan Request", "description": "The request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the `shipping_amount` and `shipping_address` values for the subscription. This type of update requires the buyer's consent.", "type": "object", "properties": { "plan_id": { "type": "string", "description": "The unique PayPal-generated ID for the plan.", "minLength": 3, "maxLength": 50 }, "quantity": { "type": "string", "description": "The quantity of the product or service in the subscription.", "pattern": "^([0-9]+|([0-9]+)?[.][0-9]+)$", "minLength": 1, "maxLength": 32 }, "shipping_amount": { "description": "The shipping charges.", "$ref": "#/components/schemas/money" }, "shipping_address": { "description": "The shipping address of the subscriber.", "$ref": "#/components/schemas/shipping_detail" }, "application_context": { "$ref": "#/components/schemas/application_context" }, "plan": { "description": "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.", "$ref": "#/components/schemas/plan_override" } } }, "subscription_revise_response": { "title": "Update Product Quantity in Subscription Response", "description": "The response to a request to update the quantity of the product or service in a subscription. You can also use this method to switch the plan and update the `shipping_amount` and `shipping_address` values for the subscription. This type of update requires the buyer's consent.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/subscription_revise_request" }, { "properties": { "plan_overridden": { "type": "boolean", "description": "Indicates whether the subscription has overridden any plan attributes.", "readOnly": true }, "links": { "type": "array", "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "readOnly": true, "items": { "readOnly": true, "$ref": "#/components/schemas/link_description" } } } } ] }, "subscriptions.revise-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "The value of a field does not conform to the expected format." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "INVALID_INTEGER_MIN_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MIN_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too small." ] } } }, { "title": "INVALID_INTEGER_MAX_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_INTEGER_MAX_VALUE" ] }, "description": { "type": "string", "enum": [ "The integer value of a field is too large." ] } } }, { "title": "MISSING_REQUEST_BODY", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUEST_BODY" ] }, "description": { "type": "string", "enum": [ "Request body is missing." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "A required field is missing." ] } } } ] } } } }, "subscriptions.revise-404": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_RESOURCE_ID", "properties": { "issue": { "type": "string", "enum": [ "INVALID_RESOURCE_ID" ] }, "description": { "type": "string", "enum": [ "Requested resource ID was not found." ] } } } ] } } } }, "subscriptions.revise-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "PLAN_PRODUCT_NOT_COMPATIBLE", "properties": { "issue": { "type": "string", "enum": [ "PLAN_PRODUCT_NOT_COMPATIBLE" ] }, "description": { "type": "string", "enum": [ "The old and the new plans should be for the same product." ] } } }, { "title": "INVALID_BILLING_CYCLE_SEQUENCE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_BILLING_CYCLE_SEQUENCE" ] }, "description": { "type": "string", "enum": [ "The provided billing cycle sequence is not available." ] } } }, { "title": "INVALID_PRICING_SCHEME", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_SCHEME" ] }, "description": { "type": "string", "enum": [ "The override plan pricing scheme should be of the same type as that of the original plan." ] } } }, { "title": "INVALID_PRICING_TIER_AMOUNT", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_AMOUNT" ] }, "description": { "type": "string", "enum": [ "Free tiers are not supported." ] } } }, { "title": "MISSING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "MISSING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "Tier(s) are missing for some quantities." ] } } }, { "title": "OVERLAPPING_PRICING_SCHEME_TIERS", "properties": { "issue": { "type": "string", "enum": [ "OVERLAPPING_PRICING_SCHEME_TIERS" ] }, "description": { "type": "string", "enum": [ "The specified quantity overlaps with multiple pricing tiers." ] } } }, { "title": "INVALID_PRICING_MODEL", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_MODEL" ] }, "description": { "type": "string", "enum": [ "The specified pricing model is not supported for trial billing cycle." ] } } }, { "title": "FIXED_PRICE_NOT_SUPPORTED", "properties": { "issue": { "type": "string", "enum": [ "FIXED_PRICE_NOT_SUPPORTED" ] }, "description": { "type": "string", "enum": [ "Fixed price is not supported for tiered pricing schemes." ] } } }, { "title": "INVALID_PRICING_TIER_QUANTITY", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PRICING_TIER_QUANTITY" ] }, "description": { "type": "string", "enum": [ "Tier starting quantity must be less than ending quantity." ] } } }, { "title": "CURRENCY_MISMATCH", "properties": { "issue": { "type": "string", "enum": [ "CURRENCY_MISMATCH" ] }, "description": { "type": "string", "enum": [ "The currency code is different from the plan's currency code." ] } } } ] } } } }, "subscription_suspend_request": { "title": "Suspend Subscription", "description": "The suspend subscription request details.", "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for suspenson of the subscription.", "minLength": 1, "maxLength": 128 } }, "required": [ "reason" ] }, "subscriptions.suspend-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } } ] } } } }, "subscriptions.suspend-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "SUBSCRIPTION_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid subscription status for suspend action; subscription status should be active." ] } } } ] } } } }, "subscription_cancel_request": { "title": "Cancel Subscription Request", "description": "The cancel subscription request details.", "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for the cancellation of a subscription.", "minLength": 1, "maxLength": 128 } }, "required": [ "reason" ] }, "subscriptions.cancel-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } } ] } } } }, "subscriptions.cancel-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "SUBSCRIPTION_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid subscription status for cancel action; subscription status should be active or suspended." ] } } } ] } } } }, "subscription_activate_request": { "title": "Activate Subscription Request", "description": "The activate subscription request details.", "type": "object", "properties": { "reason": { "type": "string", "description": "The reason for activation of a subscription. Required to reactivate the subscription.", "minLength": 1, "maxLength": 128 } } }, "subscriptions.activate-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } } ] } } } }, "subscriptions.activate-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "SUBSCRIPTION_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid subscription status for activate action; subscription status should be suspended." ] } } }, { "title": "SUBSCRIPTION_CANNOT_BE_ACTIVATED", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_CANNOT_BE_ACTIVATED" ] }, "description": { "type": "string", "enum": [ "Subscription cannot be activated after payment failure threshold has reached." ] } } }, { "title": "SUBSCRIPTION_CANNOT_BE_ACTIVATED", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_CANNOT_BE_ACTIVATED" ] }, "description": { "type": "string", "enum": [ "This subscription should be activated by the system." ] } } }, { "title": "SUBSCRIPTION_CANNOT_BE_ACTIVATED", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_CANNOT_BE_ACTIVATED" ] }, "description": { "type": "string", "enum": [ "This subscription should be activated by the merchant." ] } } } ] } } } }, "subscription_capture_request": { "title": "Charge Amount from Subscriber", "description": "The charge amount from the subscriber.", "type": "object", "properties": { "note": { "type": "string", "description": "The reason or note for the subscription charge.", "minLength": 1, "maxLength": 128 }, "capture_type": { "type": "string", "description": "The type of capture.", "minLength": 1, "maxLength": 24, "pattern": "^[A-Z_]+$", "enum": [ "OUTSTANDING_BALANCE" ] }, "amount": { "$ref": "#/components/schemas/money", "description": "The amount of the outstanding balance. This value cannot be greater than the current outstanding balance amount." } }, "required": [ "note", "capture_type", "amount" ] }, "capture_status_details": { "title": "Capture Status Details", "description": "The details of the captured payment status.", "type": "object", "properties": { "reason": { "description": "The reason why the captured payment status is `PENDING` or `DENIED`.", "type": "string", "enum": [ "BUYER_COMPLAINT", "CHARGEBACK", "ECHECK", "INTERNATIONAL_WITHDRAWAL", "OTHER", "PENDING_REVIEW", "RECEIVING_PREFERENCE_MANDATES_MANUAL_ACTION", "REFUNDED", "TRANSACTION_APPROVED_AWAITING_FUNDING", "UNILATERAL", "VERIFICATION_REQUIRED" ] } } }, "capture_status": { "type": "object", "title": "Capture Status", "description": "The status of a captured payment.", "properties": { "status": { "description": "The status of the captured payment.", "type": "string", "readOnly": true, "enum": [ "COMPLETED", "DECLINED", "PARTIALLY_REFUNDED", "PENDING", "REFUNDED" ] }, "status_details": { "description": "The details of the captured payment status.", "readOnly": true, "$ref": "#/components/schemas/capture_status_details" } } }, "amount_with_breakdown": { "type": "object", "title": "Amount with Breakdown", "description": "The breakdown details for the amount. Includes the gross, tax, fee, and shipping amounts.", "properties": { "gross_amount": { "description": "The amount for this transaction.", "readOnly": true, "$ref": "#/components/schemas/money" }, "total_item_amount": { "description": "The item total for the transaction.", "readOnly": true, "$ref": "#/components/schemas/money" }, "fee_amount": { "description": "The fee details for the transaction.", "readOnly": true, "$ref": "#/components/schemas/money" }, "shipping_amount": { "description": "The shipping amount for the transaction.", "readOnly": true, "$ref": "#/components/schemas/money" }, "tax_amount": { "description": "The tax amount for the transaction.", "readOnly": true, "$ref": "#/components/schemas/money" }, "net_amount": { "description": "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.", "readOnly": true, "$ref": "#/components/schemas/money" } }, "required": [ "gross_amount" ] }, "email_address": { "type": "string", "description": "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.
", "format": "ppaas_common_email_address_v2", "minLength": 3, "maxLength": 254, "pattern": "^.+@[^\"\\-].+$" }, "transaction": { "title": "Transaction Details", "description": "The transaction details.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/capture_status" }, { "properties": { "id": { "type": "string", "description": "The PayPal-generated transaction ID.", "minLength": 3, "maxLength": 50, "readOnly": true }, "amount_with_breakdown": { "$ref": "#/components/schemas/amount_with_breakdown" }, "payer_name": { "description": "The name of the customer.", "readOnly": true, "$ref": "#/components/schemas/name" }, "payer_email": { "description": "The email ID of the customer.", "readOnly": true, "$ref": "#/components/schemas/email_address" }, "time": { "description": "The date and time when the transaction was processed, in [Internet date and time format](https://tools.ietf.org/html/rfc3339#section-5.6).", "readOnly": true, "$ref": "#/components/schemas/date_time" } } } ], "required": [ "id", "amount_with_breakdown", "time" ] }, "subscriptions.capture-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "MISSING_REQUEST_BODY", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUEST_BODY" ] }, "description": { "type": "string", "enum": [ "Request body is missing." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "INVALID_STRING_MAX_LENGTH", "properties": { "issue": { "type": "string", "enum": [ "INVALID_STRING_MAX_LENGTH" ] }, "description": { "type": "string", "enum": [ "The value of a field is too long." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "A required field is missing." ] } } } ] } } } }, "subscriptions.capture-422": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "USER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "USER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "User account locked or closed." ] } } }, { "title": "SUBSCRIBER_ACCOUNT_LOCKED", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIBER_ACCOUNT_LOCKED" ] }, "description": { "type": "string", "enum": [ "Subscriber Account Locked." ] } } }, { "title": "SUBSCRIBER_ACCOUNT_CLOSED", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIBER_ACCOUNT_CLOSED" ] }, "description": { "type": "string", "enum": [ "Subscriber Account Closed." ] } } }, { "title": "SUBSCRIBER_ACCOUNT_RESTRICTED", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIBER_ACCOUNT_RESTRICTED" ] }, "description": { "type": "string", "enum": [ "Subscriber Account Restricted." ] } } }, { "title": "SUBSCRIPTION_STATUS_INVALID", "properties": { "issue": { "type": "string", "enum": [ "SUBSCRIPTION_STATUS_INVALID" ] }, "description": { "type": "string", "enum": [ "Invalid subscription status for capture action; subscription status should be active or suspended or expired." ] } } }, { "title": "ZERO_OUTSTANDING_BALANCE", "properties": { "issue": { "type": "string", "enum": [ "ZERO_OUTSTANDING_BALANCE" ] }, "description": { "type": "string", "enum": [ "Current outstanding balance should be greater than zero." ] } } }, { "title": "CURRENCY_MISMATCH", "properties": { "issue": { "type": "string", "enum": [ "CURRENCY_MISMATCH" ] }, "description": { "type": "string", "enum": [ "The currency code is different from the subscription's currency code." ] } } }, { "title": "AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE", "properties": { "issue": { "type": "string", "enum": [ "AMOUNT_GREATER_THAN_OUTSTANDING_BALANCE" ] }, "description": { "type": "string", "enum": [ "The capture amount can not be greater than the current outstanding balance." ] } } } ] } } } }, "transactions_list": { "title": "List Transactions", "description": "The list transactions for a subscription request details.", "type": "object", "properties": { "transactions": { "type": "array", "description": "An array of transactions.", "minItems": 0, "maxItems": 32767, "items": { "$ref": "#/components/schemas/transaction" } }, "total_items": { "type": "integer", "description": "The total number of items.", "minimum": 0, "maximum": 500000000 }, "total_pages": { "type": "integer", "description": "The total number of pages.", "minimum": 0, "maximum": 100000000 }, "links": { "type": "array", "description": "An array of request-related [HATEOAS links](/docs/api/reference/api-responses/#hateoas-links).", "readOnly": true, "minItems": 1, "maxItems": 10, "items": { "readOnly": true, "$ref": "#/components/schemas/link_description" } } } }, "subscriptions.transactions-400": { "properties": { "details": { "type": "array", "items": { "anyOf": [ { "title": "INVALID_PARAMETER_SYNTAX", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_SYNTAX" ] }, "description": { "type": "string", "enum": [ "The value of a field does not conform to the expected format." ] } } }, { "title": "INVALID_PARAMETER_VALUE", "properties": { "issue": { "type": "string", "enum": [ "INVALID_PARAMETER_VALUE" ] }, "description": { "type": "string", "enum": [ "The value of a field is invalid." ] } } }, { "title": "MISSING_REQUIRED_PARAMETER", "properties": { "issue": { "type": "string", "enum": [ "MISSING_REQUIRED_PARAMETER" ] }, "description": { "type": "string", "enum": [ "A required field is missing." ] } } } ] } } } } }, "parameters": { "prefer": { "name": "Prefer", "in": "header", "description": "The preferred server response upon successful completion of the request. Value is:", "required": false, "schema": { "type": "string", "default": "return=minimal" } }, "paypal_request_id": { "name": "PayPal-Request-Id", "in": "header", "description": "The server stores keys for 72 hours.", "required": false, "schema": { "type": "string" } }, "product_id": { "name": "product_id", "in": "query", "description": "Filters the response by a Product ID.", "required": false, "schema": { "type": "string", "minLength": 6, "maxLength": 50 } }, "plan_ids": { "name": "plan_ids", "in": "query", "description": "Filters the response by list of plan IDs. Filter supports upto 10 plan IDs.", "required": false, "schema": { "type": "string", "minimum": 3, "maximum": 270 } }, "page_size": { "name": "page_size", "in": "query", "description": "The number of items to return in the response.", "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 10 } }, "page": { "name": "page", "in": "query", "description": "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.", "schema": { "type": "integer", "minimum": 1, "maximum": 100000, "default": 1 } }, "total_required": { "name": "total_required", "in": "query", "description": "Indicates whether to show the total count in the response.", "schema": { "type": "boolean", "default": false } }, "id": { "name": "id", "in": "path", "required": true, "description": "The ID of the subscription.", "schema": { "type": "string" } }, "fields": { "name": "fields", "in": "query", "description": "List of fields that are to be returned in the response. Possible value for fields are last_failed_payment and plan.", "schema": { "type": "string", "minLength": 1, "maxLength": 100 } }, "start_time": { "name": "start_time", "in": "query", "required": true, "description": "The start time of the range of transactions to list.", "schema": { "type": "string", "format": "ppaas_date_time_v3", "minLength": 20, "maxLength": 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": { "name": "end_time", "in": "query", "required": true, "description": "The end time of the range of transactions to list.", "schema": { "type": "string", "format": "ppaas_date_time_v3", "minLength": 20, "maxLength": 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})$" } } } } }