PayPal
PayPal Plans API

The Plans API from PayPal — 5 operation(s) for plans.
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Plans API
  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 <a href="/docs/subscriptions/">Subscriptions Overview</a>.
  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
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.<br/>You can patch these attributes and objects:<table><thead><tr><th>Attribute or object</th><th>Operations</th></tr></thead><tbody><tr><td><code>description</code></td><td>replace</td></tr><tr><td><code>payment_preferences.auto_bill_outstanding</code></td><td>replace</td></tr><tr><td><code>taxes.percentage</code></td><td>replace</td></tr><tr><td><code>payment_preferences.payment_failure_threshold</code></td><td>replace</td></tr><tr><td><code>payment_preferences.setup_fee</code></td><td>replace</td></tr><tr><td><code>payment_preferences.setup_fee_failure_action</code></td><td>replace</td></tr><tr><td><code>name</code></td><td>replace</td></tr></tbody></table>
      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
components:
  schemas:
    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.
    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'
    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 <code>1</code> and <code>999</code> for <code>total_cycles</code>). Regular billing cycles can be executed infinite times (value of <code>0</code> for <code>total_cycles</code>) or a finite number of times (value between <code>1</code> and <code>999</code> for <code>total_cycles</code>).
          minimum: 0
          maximum: 999
          default: 1
      required:
      - frequency
      - tenure_type
      - sequence
    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'
    '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.
    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 t

# --- truncated at 32 KB (80 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-plans-api-openapi.yml
PayPal Plans API

Documentation

Specifications

Other Resources

OpenAPI Specification
