{"note":"OpenAPI conversion -- returning structured metadata","name":"paypal-subscriptions","description":"Subscriptions","version":"1.8","base_url":"https://api-m.sandbox.paypal.com","endpoints":16,"raw":"@lap v0.3\n# Machine-readable API spec. Each @endpoint block is one API call.\n@api Subscriptions\n@base https://api-m.sandbox.paypal.com\n@version 1.8\n@auth OAuth2\n@endpoints 16\n@toc billing(16)\n\n@endpoint POST /v1/billing/plans\n@desc Create plan\n@required {product_id: str # The ID of the product created through Catalog Products API., name: str # The plan name., billing_cycles: [map{pricing_scheme: map, frequency!: map, tenure_type!: str, sequence!: int, total_cycles: int}] # An array of billing cycles for trial billing and regular billing. A plan can have at most two trial cycles and only one regular cycle., payment_preferences: map{auto_bill_outstanding: bool, setup_fee: map, setup_fee_failure_action: str, payment_failure_threshold: int} # The payment preferences for a subscription.}\n@optional {Prefer: str=return=minimal # The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource., PayPal-Request-Id: str # The server stores keys for 72 hours., status: str(CREATED/INACTIVE/ACTIVE)=ACTIVE # The initial state of the plan. Allowed input values are CREATED and ACTIVE., description: str # The detailed description of the plan., taxes: map{percentage!: str(ppaas_common_percentage_v2), inclusive: bool} # The tax details., quantity_supported: bool=false # Indicates whether you can subscribe to this plan by providing a quantity for the goods or service.}\n@returns(200) {id: str, product_id: str, name: str, status: str, description: str, billing_cycles: [map], payment_preferences: map{auto_bill_outstanding: bool, setup_fee: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, setup_fee_failure_action: str, payment_failure_threshold: int}, taxes: map{percentage: str(ppaas_common_percentage_v2), inclusive: bool}, quantity_supported: bool, create_time: str(ppaas_date_time_v3), update_time: str(ppaas_date_time_v3), links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that shows billing plan details.\n@returns(201) {id: str, product_id: str, name: str, status: str, description: str, billing_cycles: [map], payment_preferences: map{auto_bill_outstanding: bool, setup_fee: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, setup_fee_failure_action: str, payment_failure_threshold: int}, taxes: map{percentage: str(ppaas_common_percentage_v2), inclusive: bool}, quantity_supported: bool, create_time: str(ppaas_date_time_v3), update_time: str(ppaas_date_time_v3), links: [map]} # A successful request returns the HTTP `201 Created` status code and a JSON response body that shows billing plan details.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"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}}\n\n@endpoint GET /v1/billing/plans\n@desc List plans\n@optional {Prefer: str=return=minimal # The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource., product_id: str # Filters the response by a Product ID., page_size: int=10 # The number of items to return in the response., page: int=1 # 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., total_required: bool=false # Indicates whether to show the total count in the response.}\n@returns(200) {plans: [map], total_items: int, total_pages: int, links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that lists billing plans.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 500: An internal server error has occurred.}\n\n@endpoint GET /v1/billing/plans/{id}\n@desc Show plan details\n@required {id: str # The ID of the subscription.}\n@returns(200) {id: str, product_id: str, name: str, status: str, description: str, billing_cycles: [map], payment_preferences: map{auto_bill_outstanding: bool, setup_fee: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, setup_fee_failure_action: str, payment_failure_threshold: int}, taxes: map{percentage: str(ppaas_common_percentage_v2), inclusive: bool}, quantity_supported: bool, create_time: str(ppaas_date_time_v3), update_time: str(ppaas_date_time_v3), links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that shows plan details.\n@errors {401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 500: An internal server error has occurred.}\n\n@endpoint PATCH /v1/billing/plans/{id}\n@desc Update plan\n@required {id: str # The ID of the subscription.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n\n@endpoint POST /v1/billing/plans/{id}/activate\n@desc Activate plan\n@required {id: str # The ID of the subscription.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n\n@endpoint POST /v1/billing/plans/{id}/deactivate\n@desc Deactivate plan\n@required {id: str # The ID of the subscription.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n\n@endpoint POST /v1/billing/plans/{id}/update-pricing-schemes\n@desc Update pricing\n@required {id: str # The ID of the subscription., pricing_schemes: [map{billing_cycle_sequence!: int, pricing_scheme!: map}] # An array of pricing schemes.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"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\"}}]}}]}\n\n@endpoint POST /v1/billing/subscriptions\n@desc Create subscription\n@required {plan_id: str # The ID of the plan.}\n@optional {Prefer: str=return=minimal # The preferred server response upon successful completion of the request. Value is:return=minimal. The server returns a minimal response to optimize communication between the API caller and the server. A minimal response includes the id, status and HATEOAS links.return=representation. The server returns a complete resource representation, including the current state of the resource., PayPal-Request-Id: str # The server stores keys for 72 hours., start_time: str(ppaas_date_time_v3) # 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., quantity: str # The quantity of the product in the subscription., shipping_amount: map{currency_code!: str(ppaas_common_currency_code_v2), value!: str} # The currency and amount for a financial transaction, such as a balance or payment due., subscriber: any, auto_renewal: bool=false # DEPRECATED. Indicates whether the subscription auto-renews after the billing cycles complete., application_context: map{brand_name: str, locale: str(ppaas_common_language_v3), shipping_preference: str, user_action: str, payment_method: map, return_url!: str(uri), cancel_url!: str(uri)} # The application context, which customizes the payer experience during the subscription approval process with PayPal., custom_id: str # The custom id for the subscription. Can be invoice id., plan: map{billing_cycles: [map], payment_preferences: map, taxes: map} # 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., merchant_inventory: any}\n@returns(200) A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.\n@returns(201) A successful request returns the HTTP `201 Created` status code and a JSON response body that shows subscription details.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"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\"}}\n\n@endpoint GET /v1/billing/subscriptions/{id}\n@desc Show subscription details\n@required {id: str # The ID of the subscription.}\n@optional {fields: str # List of fields that are to be returned in the response. Possible value for fields are last_failed_payment and plan.}\n@returns(200) A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.\n@errors {401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 500: An internal server error has occurred.}\n\n@endpoint PATCH /v1/billing/subscriptions/{id}\n@desc Update subscription\n@required {id: str # The ID of the subscription.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {400: Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n\n@endpoint POST /v1/billing/subscriptions/{id}/revise\n@desc Revise plan or quantity of subscription\n@required {id: str # The ID of the subscription.}\n@optional {plan_id: str # The unique PayPal-generated ID for the plan., quantity: str # The quantity of the product or service in the subscription., shipping_amount: map{currency_code!: str(ppaas_common_currency_code_v2), value!: str} # The currency and amount for a financial transaction, such as a balance or payment due., shipping_address: map{name: map, type: str, options: [map], address: map} # The shipping details., application_context: map{brand_name: str, locale: str(ppaas_common_language_v3), shipping_preference: str, payment_method: map, return_url!: str(uri), cancel_url!: str(uri)} # The application context, which customizes the payer experience during the subscription approval process with PayPal., plan: map{billing_cycles: [map], payment_preferences: map, taxes: map} # 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.}\n@returns(200) {plan_id: str, quantity: str, shipping_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, shipping_address: map{name: map{full_name: str}, type: str, options: [map], address: map{address_line_1: str, address_line_2: str, admin_area_2: str, admin_area_1: str, postal_code: str, country_code: str(ppaas_common_country_code_v2)}}, plan: map{billing_cycles: [map], payment_preferences: map{auto_bill_outstanding: bool, setup_fee: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, setup_fee_failure_action: str, payment_failure_threshold: int}, taxes: map{percentage: str(ppaas_common_percentage_v2), inclusive: bool}}, plan_overridden: bool, links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"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\"}}\n\n@endpoint POST /v1/billing/subscriptions/{id}/suspend\n@desc Suspend subscription\n@required {id: str # The ID of the subscription., reason: str # The reason for suspension of the Subscription.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"reason\":\"Item out of stock\"}\n\n@endpoint POST /v1/billing/subscriptions/{id}/cancel\n@desc Cancel subscription\n@required {id: str # The ID of the subscription., reason: str # The reason for the cancellation of a subscription.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"reason\":\"Not satisfied with the service\"}\n\n@endpoint POST /v1/billing/subscriptions/{id}/activate\n@desc Activate subscription\n@required {id: str # The ID of the subscription.}\n@optional {reason: str # The reason for activation of a subscription. Required to reactivate the subscription.}\n@returns(204) A successful request returns the HTTP `204 No Content` status code with no JSON response body.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"reason\":\"Reactivating the subscription\"}\n\n@endpoint POST /v1/billing/subscriptions/{id}/capture\n@desc Capture authorized payment on subscription\n@required {id: str # The ID of the subscription., note: str # The reason or note for the subscription charge., capture_type: str # The type of capture., amount: map{currency_code!: str(ppaas_common_currency_code_v2), value!: str} # The currency and amount for a financial transaction, such as a balance or payment due.}\n@optional {PayPal-Request-Id: str # The server stores keys for 72 hours.}\n@returns(200) {status: str, id: str, amount_with_breakdown: map{gross_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, total_item_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, fee_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, shipping_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, tax_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}, net_amount: map{currency_code: str(ppaas_common_currency_code_v2), value: str}}, payer_name: map{prefix: str, given_name: str, surname: str, middle_name: str, suffix: str, full_name: str}, payer_email: str(ppaas_common_email_address_v2), time: str(ppaas_date_time_v3)} # A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.\n@returns(202) Request Accepted.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 422: The requested action could not be performed, semantically incorrect, or failed business validation., 500: An internal server error has occurred.}\n@example_request {\"note\":\"Charging as the balance reached the limit\",\"capture_type\":\"OUTSTANDING_BALANCE\",\"amount\":{\"currency_code\":\"USD\",\"value\":\"100\"}}\n\n@endpoint GET /v1/billing/subscriptions/{id}/transactions\n@desc List transactions for subscription\n@required {id: str # The ID of the subscription., start_time: str # The start time of the range of transactions to list., end_time: str # The end time of the range of transactions to list.}\n@returns(200) {transactions: [map], total_items: int, total_pages: int, links: [map]} # A successful request returns the HTTP `200 OK` status code and a JSON response body that shows subscription details.\n@errors {400: Bad Request. Request is not well-formed, syntactically incorrect, or violates schema., 401: Authentication failed due to missing authorization header, or invalid authentication credentials., 403: Authorization failed due to insufficient permissions., 404: The specified resource does not exist., 500: An internal server error has occurred.}\n\n@end\n"}