PayPal Billing API

openapi: 3.0.3
info:
  title: Paypal Subscriptions Authorizations Billing 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: Billing
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:
      - Billing
    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:
      - Billing
  /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:
      - Billing
    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:
      - Billing
  /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:
      - Billing
  /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:
      - Billing
  /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:
      - Billing
  /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:
      - Billing
  /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:
    

# --- truncated at 32 KB (190 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paypal/refs/heads/main/openapi/paypal-billing-api-openapi.yml