> ## Documentation Index
> Fetch the complete documentation index at: https://developer.vetcove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Import or update a legacy patient care plan

> Imports or updates a legacy patient care plan for a clinic patient.

If an existing patient care plan for the same PIM patient ID and core Care Plan ID already exists and has a `status` of `IMPORTED`, it will be updated instead. Patient care plans with any other status, including imported patient care plans that have already been marked `ACTIVE`, cannot be updated through this endpoint.



## OpenAPI

````yaml post /ext/v2/patient-care-plans/import/
openapi: 3.1.0
info:
  description: ''
  title: NinjaAPI
  version: 2.0.0
servers:
  - url: https://connect.vetcove.com/
security: []
paths:
  /ext/v2/patient-care-plans/import/:
    post:
      tags:
        - Care Plans
      summary: Import or update a legacy patient care plan
      description: >-
        Imports or updates a legacy patient care plan for a clinic patient.


        If an existing patient care plan for the same PIM patient ID and core
        Care Plan ID already exists and has a `status` of `IMPORTED`, it will be
        updated instead. Patient care plans with any other status, including
        imported patient care plans that have already been marked `ACTIVE`,
        cannot be updated through this endpoint.
      operationId: legacy_patient_care_plans_import
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalLegacyPatientCarePlanImportSchema'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPatientCarePlanSchema'
          description: OK
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalPatientCarePlanSchema'
          description: Created
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalImportDisambiguationErrorSchema'
          description: Conflict
      security:
        - ExternalAPIAuth: []
components:
  schemas:
    ExternalLegacyPatientCarePlanImportSchema:
      description: Schema for importing a legacy patient care plan via the external API.
      properties:
        amount_paid:
          description: The amount paid for the care plan
          minimum: 0
          title: Amount Paid
          type: integer
        care_benefits:
          description: The care benefits to import for the care plan
          items:
            $ref: '#/components/schemas/ExternalLegacyPatientCareBenefitImportSchema'
          title: Care Benefits
          type: array
        care_plan_id:
          description: The core Care Plan ID to enroll the patient into
          title: Care Plan Id
          type: integer
        clinic_client_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Optional Vetcove client ID. When provided, bypasses PIM ID lookup
            and resolves the client by primary key (scoped to clinic). Use this
            to disambiguate when multiple clients share the same pim_client_id.
          title: Clinic Client Id
        clinic_id:
          description: The clinic ID for the patient and client being imported
          title: Clinic Id
          type: integer
        clinic_patient_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Optional Vetcove patient ID. When provided, bypasses PIM ID lookup
            and resolves the patient by primary key (scoped to clinic). Use this
            to disambiguate when multiple patients share the same
            pim_patient_id.
          title: Clinic Patient Id
        end_date:
          description: >-
            End date for the care plan (YYYY-MM-DD). This is non-inclusive,
            meaning a plan ending on 2/1/2026 would not be considered
            active/usable on 2/1/2026.
          format: date
          title: End Date
          type: string
        enrollment_fee:
          description: The enrollment fee of the care plan
          minimum: 0
          title: Enrollment Fee
          type: integer
        is_billed_monthly:
          description: Whether billing is monthly (True) or upfront (False)
          title: Is Billed Monthly
          type: boolean
        next_plan_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: Optional next core Care Plan ID for automatic renewal
          title: Next Plan Id
        payment_method_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            Optional Vetcove payment method ID. When provided, takes precedence
            over stripe_payment_method_id and resolves the payment method by
            primary key (scoped to the client). Both payment method fields are
            optional for all statuses. Omitting both means the payment method
            must be updated later before billing.
          title: Payment Method Id
        pim_client_id:
          description: The PIM client ID to import the care plan for
          title: Pim Client Id
          type: string
        pim_patient_id:
          description: The PIM patient ID to import the care plan for
          title: Pim Patient Id
          type: string
        plan_cost:
          description: The cost of the care plan
          minimum: 0
          title: Plan Cost
          type: integer
        should_renew:
          description: Whether the plan should automatically renew at the end of term
          title: Should Renew
          type: boolean
        start_date:
          description: Start date for the enrollment (YYYY-MM-DD)
          format: date
          title: Start Date
          type: string
        status:
          $ref: '#/components/schemas/PatientCarePlanStatus'
          description: >-
            The status of the care plan. Must be one of: IMPORTED, ACTIVE,
            TERMINATED
        stripe_payment_method_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Optional legacy Stripe payment method ID to use for billing.
            payment_method_id takes precedence when both fields are provided.
            Both payment method fields are optional for all statuses. Omitting
            both means the payment method must be updated later before billing.
          title: Stripe Payment Method Id
      required:
        - clinic_id
        - pim_patient_id
        - pim_client_id
        - care_plan_id
        - start_date
        - end_date
        - plan_cost
        - enrollment_fee
        - is_billed_monthly
        - should_renew
        - status
        - amount_paid
        - care_benefits
      title: ExternalLegacyPatientCarePlanImportSchema
      type: object
    ExternalPatientCarePlanSchema:
      properties:
        care_plan_id:
          description: The ID of the Care Plan this patient-specific plan is linked to
          title: Care Plan Id
          type: integer
        care_plan_kind:
          $ref: '#/components/schemas/CarePlanKind'
          description: The type of the care plan
        care_plan_name:
          description: The name of the care plan this patient care plan is linked to
          title: Care Plan Name
          type: string
        clinic_client_id:
          description: >-
            The ID of the clinic client this patient care plan is associated
            with
          title: Clinic Client Id
          type: integer
        clinic_id:
          description: The ID of the clinic this patient care plan is associated with
          title: Clinic Id
          type: integer
        clinic_patient_id:
          description: The ID of the clinic patient this care plan is associated with
          title: Clinic Patient Id
          type: integer
        core_plan_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: >-
            The ID of the core patient care plan this one is linked to, if this
            is an add-on plan
          title: Core Plan Id
        deactivated_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          description: When this care plan was deactivated, if applicable
          title: Deactivated At
        deactivated_by:
          anyOf:
            - type: string
            - type: 'null'
          description: The name of the user who deactivated the care plan, if applicable
          title: Deactivated By
        end_date:
          description: >-
            End date for the care plan (YYYY-MM-DD). This is non-inclusive,
            meaning a plan ending on 2/1/2026 would not be considered
            active/usable on 2/1/2026.
          format: date
          title: End Date
          type: string
        enrollment_fee:
          description: The enrollment fee of the care plan
          minimum: 0
          title: Enrollment Fee
          type: integer
        id:
          description: The unique identifier for the patient care plan
          title: Id
          type: integer
        is_billed_monthly:
          description: Whether the care plan is billed monthly or upfront
          title: Is Billed Monthly
          type: boolean
        monthly_cost:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: >-
            The monthly cost of the care plan, in cents. Only applicable to
            monthly billed care plans.
          title: Monthly Cost
        next_payment_date:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: The date of the next payment for the care plan, if applicable
          title: Next Payment Date
        next_plan_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: The ID of the next care plan, if applicable
          title: Next Plan Id
        payment_method_id:
          anyOf:
            - type: integer
            - type: 'null'
          description: The ID of the payment method associated with this care plan
          title: Payment Method Id
        plan_cost:
          description: The cost of the care plan
          minimum: 0
          title: Plan Cost
          type: integer
        remaining_balance:
          description: The remaining balance of the care plan, in cents
          title: Remaining Balance
          type: integer
        should_renew:
          description: Whether this care plan will automatically be renewed
          title: Should Renew
          type: boolean
        start_date:
          description: The start date of the care plan
          format: date
          title: Start Date
          type: string
        status:
          anyOf:
            - $ref: '#/components/schemas/PatientCarePlanStatus'
            - const: ''
              type: string
          description: The status of the patient care plan
          title: Status
      required:
        - id
        - clinic_patient_id
        - clinic_id
        - clinic_client_id
        - care_plan_id
        - start_date
        - end_date
        - deactivated_at
        - status
        - core_plan_id
        - next_plan_id
        - should_renew
        - plan_cost
        - enrollment_fee
        - care_plan_name
        - care_plan_kind
        - deactivated_by
        - next_payment_date
        - remaining_balance
        - is_billed_monthly
        - monthly_cost
        - payment_method_id
      title: ExternalPatientCarePlanSchema
      type: object
    ExternalImportDisambiguationErrorSchema:
      description: >-
        Returned when a PIM ID matches multiple patients or clients and the
        system cannot auto-resolve to a single record. The 'details.candidates'
        array lists the matching records, and 'details.resolution_field'
        indicates which request field to populate with the chosen candidate's
        ID.
      properties:
        error:
          $ref: '#/components/schemas/ExternalDisambiguationErrorBodySchema'
          description: >-
            The disambiguation error. Contains candidate records and the field
            to use for resolution.
      required:
        - error
      title: ExternalImportDisambiguationErrorSchema
      type: object
    ExternalLegacyPatientCareBenefitImportSchema:
      description: Schema for uploading legacy patient care benefit data.
      properties:
        care_benefit_id:
          description: The ID of the care benefit to upload
          title: Care Benefit Id
          type: integer
        points_used:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: The number of points used for the care benefit if applicable
          title: Points Used
        redemptions:
          description: The redemptions for the care benefit
          items:
            $ref: >-
              #/components/schemas/ExternalLegacyPatientCareBenefitRedemptionImportSchema
          title: Redemptions
          type: array
      required:
        - care_benefit_id
        - redemptions
      title: ExternalLegacyPatientCareBenefitImportSchema
      type: object
    PatientCarePlanStatus:
      enum:
        - IMPORTED
        - CLIENT_CREATED
        - CLINIC_CREATED
        - ACTIVE
        - TERMINATED
        - PAYMENT_FAILED
        - SUSPENDED
      title: PatientCarePlanStatus
      type: string
    CarePlanKind:
      enum:
        - CORE
        - ADD_ON
        - SERVICE_PACKAGE
      title: CarePlanKind
      type: string
    ExternalDisambiguationErrorBodySchema:
      properties:
        details:
          $ref: '#/components/schemas/ExternalDisambiguationDetailsSchema'
          description: >-
            Contains the resolution field and candidate records for
            disambiguation.
        message:
          description: A human-readable description of the error.
          title: Message
          type: string
        type:
          const: disambiguation_required
          description: The error type.
          title: Type
          type: string
      required:
        - type
        - message
        - details
      title: ExternalDisambiguationErrorBodySchema
      type: object
    ExternalLegacyPatientCareBenefitRedemptionImportSchema:
      description: Schema for uploading legacy patient care benefit redemption data.
      properties:
        amount_discounted:
          description: The amount discounted for the care benefit
          minimum: 0
          title: Amount Discounted
          type: integer
        points_redeemed:
          anyOf:
            - minimum: 0
              type: integer
            - type: 'null'
          description: The number of points redeemed for the care benefit if applicable
          title: Points Redeemed
      required:
        - amount_discounted
      title: ExternalLegacyPatientCareBenefitRedemptionImportSchema
      type: object
    ExternalDisambiguationDetailsSchema:
      properties:
        candidates:
          description: >-
            The candidate records that matched the given PIM ID. Re-submit the
            request with the resolution field set to the chosen candidate's
            'id'.
          items:
            $ref: '#/components/schemas/ExternalDisambiguationCandidateSchema'
          title: Candidates
          type: array
        resolution_field:
          $ref: '#/components/schemas/DisambiguationResolutionField'
          description: >-
            The request field to populate with a candidate ID to resolve the
            ambiguity.
      required:
        - resolution_field
        - candidates
      title: ExternalDisambiguationDetailsSchema
      type: object
    ExternalDisambiguationCandidateSchema:
      description: A candidate record returned when PIM ID resolution is ambiguous.
      properties:
        id:
          description: >-
            The Vetcove ID of the candidate. Use this value for
            'clinic_patient_id' or 'clinic_client_id' to disambiguate.
          title: Id
          type: integer
        name:
          description: The name of the patient or client.
          title: Name
          type: string
        was_imported_from_legacy_source:
          description: Whether this record was imported from the clinic's legacy PIMS.
          title: Was Imported From Legacy Source
          type: boolean
      required:
        - id
        - name
        - was_imported_from_legacy_source
      title: ExternalDisambiguationCandidateSchema
      type: object
    DisambiguationResolutionField:
      enum:
        - clinic_patient_id
        - clinic_client_id
      title: DisambiguationResolutionField
      type: string
  securitySchemes:
    ExternalAPIAuth:
      scheme: bearer
      type: http

````