openapi: 3.2.0
info:
  description: '### Pagination

    Requests that return multiple items will be paginated to 100 items by default.

    You can specify further pages with the ?page parameter. For some resources, you can also set a custom

    page size up to 1000 with the ?per_page parameter.


    X-Total-Count – Total number of results

    X-Limit – Number results per page

    X-Page-Last – Number of last page

    X-Page – Current Page Number (starts from 0)'
  title: partners1 Payment Plans API
  version: '1'
servers:
- url: sandbox.collectly.co/api/api/partners/v1
security:
- ApiKey: []
tags:
- name: Payment Plans
paths:
  /practices/{practice_id}/patients/{patient_id}/payment-plans:
    get:
      parameters:
      - description: Practice ID in which the requested resource exists
        in: path
        name: practice_id
        required: true
        schema:
          type: string
      - description: Patient ID from your integration who owns the resource
        in: path
        name: patient_id
        required: true
        schema:
          type: string
      - description: Page number of dataset
        in: query
        name: page
        required: false
        schema:
          minimum: 0
          type: integer
      - description: Custom page size of dataset
        in: query
        name: per_page
        required: false
        schema:
          default: 100
          type: integer
      - description: String with a comma-separated list of parameters by which to sort the dataset. To specify a descending order, add a "-" character before the parameter. For example, `?sort=-created_at,id`
        in: query
        name: sort
        required: false
        schema:
          example: ''
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPlan'
          description: OK
          headers:
            X-Limit:
              description: Number results per page. Requests that return multiple items will be paginated to 100 items by default. You can specify further pages with the `?page` parameter. For some resources, you can also set a custom page size up to 1000 with the `?per_page` parameter.
              schema:
                type: integer
            X-Page:
              description: Current Page Number (starts from 0)
              schema:
                type: integer
            X-Page-Last:
              description: Number of last page
              schema:
                type: integer
            X-Total-Count:
              description: Total number of results
              schema:
                type: integer
      summary: Retrieve a patient's payment plan or list of all payment plans
      tags:
      - Payment Plans
      operationId: getPracticesByPracticeIdPatientsByPatientIdPaymentPlans
      x-operation-id-source: derived
    post:
      description: 'Create a new payment plan for a patient.


        There are two types of payment plans:

        1. `type: "standard"`. The standard post-service payment plan may be created only in case there is an outstanding

        patient balance. Standard payment plan checks the current patient balance on every installment and charges

        `installment` amount, but not more than the current balance of the patient.

        Payment plan also stops when the total installments sum reaches the "total_amount". The last installment in

        this case may be less than the `installment`. E.g. plan for `total_amount` of $100 and installment of $40

        the last installment amount is $20.


        2. type: "upfront". This is a pre-service payment plan. It does not check the current patient balance, may be

        started with any patient balance and will be charged up to a "total_amount".


        One of the `collectly_payment_method_id`, `external_payment_method_id` is required since

        payment plan requires a payment method. `external_payment_method_id` can be used only for patients that

        have `metadata.stripe_customer_id` set.'
      parameters:
      - description: Practice ID in which the requested resource exists
        in: path
        name: practice_id
        required: true
        schema:
          type: string
      - description: Patient ID from your integration who owns the resource
        in: path
        name: patient_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentPlan'
        description: Request Body
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPlan'
          description: OK
          headers: {}
      summary: Create a new payment plan for a patient
      tags:
      - Payment Plans
      operationId: postPracticesByPracticeIdPatientsByPatientIdPaymentPlans
      x-operation-id-source: derived
  /practices/{practice_id}/patients/{patient_id}/payment-plans/{payment_plans}:
    delete:
      parameters:
      - description: Practice ID in which the requested resource exists
        in: path
        name: practice_id
        required: true
        schema:
          type: string
      - description: Patient ID from your integration who owns the resource
        in: path
        name: patient_id
        required: true
        schema:
          type: string
      - description: Resource Identifier
        in: path
        name: payment_plans
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPlan'
          description: OK
          headers: {}
      summary: Cancel an active payment plan
      tags:
      - Payment Plans
      operationId: deletePracticesByPracticeIdPatientsByPatientIdPaymentPlansByPaymentPlans
      x-operation-id-source: derived
    get:
      parameters:
      - description: Practice ID in which the requested resource exists
        in: path
        name: practice_id
        required: true
        schema:
          type: string
      - description: Patient ID from your integration who owns the resource
        in: path
        name: patient_id
        required: true
        schema:
          type: string
      - description: Resource Identifier
        in: path
        name: payment_plans
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPlan'
          description: OK
          headers: {}
      summary: Retrieve a patient's payment plan or list of all payment plans
      tags:
      - Payment Plans
      operationId: getPracticesByPracticeIdPatientsByPatientIdPaymentPlansByPaymentPlans
      x-operation-id-source: derived
    patch:
      description: 'Update the payment plan or reschedule a regular payment date.


        Properties you can update for any payment plan type:

        - ''start_date'' - all next installments will be charged starting from this date.

        The date is required when you change a period type or you update a plan with missed payments.

        The start date must not be in the past. The interval between the last scheduled

        payment to the new start date must be no more than two plan periods (month, 2 weeks, week).

        - ''installment''

        - ''period_type''

        - ''collectly_payment_method_id''

        - ''external_payment_method_id'' - can be used only for patients that have `metadata.stripe_customer_id` set

        If you update an upfront payment plan you can additionally set new ''total_amount''.

        All changes will take effect immediately.'
      parameters:
      - description: Practice ID in which the requested resource exists
        in: path
        name: practice_id
        required: true
        schema:
          type: string
      - description: Patient ID from your integration who owns the resource
        in: path
        name: patient_id
        required: true
        schema:
          type: string
      - description: Resource Identifier
        in: path
        name: payment_plans
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PaymentPlan'
        description: Request Body
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentPlan'
          description: OK
          headers: {}
      summary: Update the payment plan or reschedule a regular payment date
      tags:
      - Payment Plans
      operationId: patchPracticesByPracticeIdPatientsByPatientIdPaymentPlansByPaymentPlans
      x-operation-id-source: derived
components:
  schemas:
    PaymentPlan:
      properties:
        collectly_id:
          description: Unique Collectly resource ID
          readOnly: true
          type: string
        collectly_payment_method_id:
          description: Collectly payment method ID which you can obtain from "/payment-methods" endpoint
          type:
          - string
          - 'null'
        created_at:
          readOnly: true
        installment:
          description: Amount to charge every week/2nd week/month according to period_type.
          minimum: 0.01
          type: number
        location_id:
          description: This field determines where to route funds for pre-service payment plans in case multiple bank accounts are connected. Should be empty in other cases.
          type:
          - string
          - 'null'
        n_installments:
          description: The total count of planned payments for this payment plan.
          format: int32
          readOnly: true
          type: integer
        next_payment_date:
          description: datetime of the next planned charge
          format: date
          readOnly: true
          type: string
        payments_made:
          description: The count of already charged payments for this payment plan.
          format: int32
          readOnly: true
          type: integer
        period_type:
          default: monthly
          description: Determines the frequency of installments.
          enum:
          - monthly
          - weekly
          - biweekly
          - semimonthly
          type: string
        start_date:
          description: 'ISO-8601 date format. The date when the first installment will be charged. Must not be in the past. Successive installment dates are computed according to the "period_type". Convert the start date to UTC timezone. '
          format: date
          type: string
        status:
          description: Current status of the payment plan
          enum:
          - not_subscribed
          - subscribed
          - paid
          - cancelled
          - declined
          - failed
          readOnly: true
          type:
          - string
          - 'null'
        total_amount:
          description: Total amount to be charged on the payment plan.It is always equal to patient balance at payment plan subscription momentfor the "standard" type.
          minimum: 0.01
          type:
          - number
          - 'null'
        type:
          default: standard
          description: '"standard" - post-service payment plan, "upfront" - pre-service payment plan'
          enum:
          - standard
          - upfront
          type: string
      required:
      - installment
      type: object
  securitySchemes:
    ApiKey:
      in: header
      name: Authorization
      type: apiKey
x-provenance:
  method: searched
  source: https://docs.collectly.co/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://docs.collectly.co/reference/delete_practices-practice-id-insurance-policies-insurance-policies.md
  - https://docs.collectly.co/reference/delete_practices-practice-id-patients-patient-id-checkout-patient-checkout.md
  - https://docs.collectly.co/reference/delete_practices-practice-id-patients-patient-id-payment-methods-payment-methods.md
  - https://docs.collectly.co/reference/delete_practices-practice-id-patients-patient-id-payment-plans-payment-plans.md
  - https://docs.collectly.co/reference/delete_practices-practice-id-patients-patient-id-subscriptions-subscriptions.md
  - https://docs.collectly.co/reference/get_company.md
  - https://docs.collectly.co/reference/get_patient-forms-patient-forms.md
  - https://docs.collectly.co/reference/get_patient-forms.md
  - https://docs.collectly.co/reference/get_practices-info-practices-info.md
  - https://docs.collectly.co/reference/get_practices-info.md
  - https://docs.collectly.co/reference/get_practices-practice-id-appointments-appointments.md
  - https://docs.collectly.co/reference/get_practices-practice-id-appointments.md
  - https://docs.collectly.co/reference/get_practices-practice-id-insurance-companies-insurance-companies.md
  - https://docs.collectly.co/reference/get_practices-practice-id-insurance-companies.md
  - https://docs.collectly.co/reference/get_practices-practice-id-insurance-policies-insurance-policies.md
  - https://docs.collectly.co/reference/get_practices-practice-id-insurance-policies.md
  - https://docs.collectly.co/reference/get_practices-practice-id-locations-locations.md
  - https://docs.collectly.co/reference/get_practices-practice-id-locations.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-payment-methods-payment-methods.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-payment-methods.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-payment-plans-payment-plans.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-payment-plans.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-statement-statements.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-statement.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-subscriptions-subscriptions.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patient-id-subscriptions.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients-patients.md
  - https://docs.collectly.co/reference/get_practices-practice-id-patients.md
  - https://docs.collectly.co/reference/get_practices-practice-id-payments-payments.md
  - https://docs.collectly.co/reference/get_practices-practice-id-payments.md
  - https://docs.collectly.co/reference/get_practices-practice-id-providers-providers.md
  - https://docs.collectly.co/reference/get_practices-practice-id-providers.md
  - https://docs.collectly.co/reference/get_practices-practice-id-unmapped-patients-unmapped-patients.md
  - https://docs.collectly.co/reference/get_practices-practice-id-unmapped-patients.md
  - https://docs.collectly.co/reference/get_practices-practices.md
  - https://docs.collectly.co/reference/get_practices.md
  - https://docs.collectly.co/reference/get_users-users.md
  - https://docs.collectly.co/reference/get_users.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-appointments-appointments.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-insurance-companies-insurance-companies.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-insurance-policies-insurance-policies.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-locations-locations.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-patients-patient-id-payment-plans-payment-plans.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-patients-patient-id-subscriptions-subscriptions.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-patients-patients.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-providers-providers.md
  - https://docs.collectly.co/reference/patch_practices-practice-id-unmapped-patients-unmapped-patients.md
  - https://docs.collectly.co/reference/patch_practices-practices.md
  - https://docs.collectly.co/reference/patch_users-users.md
  - https://docs.collectly.co/reference/post_login.md
  - https://docs.collectly.co/reference/post_patient-forms-patient-forms-sign.md
  - https://docs.collectly.co/reference/post_patient-forms.md
  - https://docs.collectly.co/reference/post_patient-lookup.md
  - https://docs.collectly.co/reference/post_practices-practice-id-appointments.md
  - https://docs.collectly.co/reference/post_practices-practice-id-insurance-companies.md
  - https://docs.collectly.co/reference/post_practices-practice-id-insurance-policies.md
  - https://docs.collectly.co/reference/post_practices-practice-id-locations.md
  - https://docs.collectly.co/reference/post_practices-practice-id-patients-patient-id-payment-methods-payment-methods-charge.md
  - https://docs.collectly.co/reference/post_practices-practice-id-patients-patient-id-payment-methods.md
  - https://docs.collectly.co/reference/post_practices-practice-id-patients-patient-id-payment-plans-request.md
  - https://docs.collectly.co/reference/post_practices-practice-id-patients-patient-id-payment-plans.md
  - https://docs.collectly.co/reference/post_practices-practice-id-patients-patient-id-statement.md
  - https://docs.collectly.co/reference/post_practices-practice-id-patients-patient-id-subscriptions.md
  - https://docs.collectly.co/reference/post_practices-practice-id-patients.md
  - https://docs.collectly.co/reference/post_practices-practice-id-payments-payment-id-refund.md
  - https://docs.collectly.co/reference/post_practices-practice-id-providers.md
  - https://docs.collectly.co/reference/post_practices-practice-id-store-payment-method.md
  - https://docs.collectly.co/reference/post_practices-practice-id-unmapped-patients.md
  - https://docs.collectly.co/reference/post_practices-practices-post-apply-payment.md
  - https://docs.collectly.co/reference/post_practices.md
  - https://docs.collectly.co/reference/post_users.md
  merge:
    pages: 71
    deduped: 186
    conflicts_kept_first: 0