---
title: "Create a new payment plan for a patient."
method: POST
path: "/practices/{practice_id}/patients/{patient_id}/payment-plans"
tags: ["payment_plans"]
---

# Create a new payment plan for a patient.

`POST /practices/{practice_id}/patients/{patient_id}/payment-plans`

## Request

- Base URL: `sandbox.collectly.co/api/api/partners/v1` (relative, and the document’s source URL is not known)
- URL: `sandbox.collectly.co/api/api/partners/v1/practices/{practice_id}/patients/{patient_id}/payment-plans`
- Auth: API key in header `Authorization`

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.

## Path parameters

- `practice_id` string, required
- `patient_id` string, required

## Request body

- PaymentPlan
  - `collectly_id` string: Unique Collectly resource ID
  - `collectly_payment_method_id` string, nullable: Collectly payment method ID which you can obtain from "/payment-methods" endpoint
  - `created_at` unknown
  - `installment` number, required: Amount to charge every week/2nd week/month according to period_type.
  - `location_id` string, nullable: 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.
  - `n_installments` integer: The total count of planned payments for this payment plan.
  - `next_payment_date` string, date: datetime of the next planned charge
  - `payments_made` integer: The count of already charged payments for this payment plan.
  - `period_type` 'monthly' | 'weekly' | 'biweekly' | 'semimonthly': Determines the frequency of installments.
  - `start_date` string, date: 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.
  - `status` 'not_subscribed' | 'subscribed' | 'paid' | 'cancelled' | 'declined' | 'failed', nullable: Current status of the payment plan
  - `total_amount` number, nullable: Total amount to be charged on the payment plan.It is always equal to patient balance at payment plan subscription momentfor the "standard" type.
  - `type` 'standard' | 'upfront': "standard" - post-service payment plan, "upfront" - pre-service payment plan

## Response `200`

OK

- PaymentPlan
  - `collectly_id` string: Unique Collectly resource ID
  - `collectly_payment_method_id` string, nullable: Collectly payment method ID which you can obtain from "/payment-methods" endpoint
  - `created_at` unknown
  - `installment` number, required: Amount to charge every week/2nd week/month according to period_type.
  - `location_id` string, nullable: 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.
  - `n_installments` integer: The total count of planned payments for this payment plan.
  - `next_payment_date` string, date: datetime of the next planned charge
  - `payments_made` integer: The count of already charged payments for this payment plan.
  - `period_type` 'monthly' | 'weekly' | 'biweekly' | 'semimonthly': Determines the frequency of installments.
  - `start_date` string, date: 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.
  - `status` 'not_subscribed' | 'subscribed' | 'paid' | 'cancelled' | 'declined' | 'failed', nullable: Current status of the payment plan
  - `total_amount` number, nullable: Total amount to be charged on the payment plan.It is always equal to patient balance at payment plan subscription momentfor the "standard" type.
  - `type` 'standard' | 'upfront': "standard" - post-service payment plan, "upfront" - pre-service payment plan

## Changes

- **2026-11-03** `a45575a6e4b8`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/collectly/apis/partners1/changes/practices/:practice_id/patients/:patient_id/payment-plans/post.md)

---

[API](https://skmtc.dev/collectly/apis/partners1.md) - [All operations](https://skmtc.dev/collectly/apis/partners1/llms.txt) - [OpenAPI document](https://skmtc.dev/collectly/apis/partners1/revisions/a45575a6e4b8?raw)