---
title: "Create patient refund"
method: POST
path: "/api/patient-refunds/v1"
tags: ["v1"]
---

# Create patient refund

`POST /api/patient-refunds/v1`

Creates a new patient refund record and returns the newly created PatientRefund object.
The allocations can describe whether the refund is being applied toward a specific service line,
claim, or billing provider.

## Headers

- `Authorization` string, required

## Request body

- object
  - `amount_cents` integer, required
  - `refund_timestamp` string, date-time
  - `refund_note` string
  - `patient_external_id` string, required
  - `allocations` TypeFinancialsAllocationCreate[], required
    - `amount_cents` integer, required
    - `target` union, required — Allocation targets describe whether the portion of a payment is being applied toward a specific service line, claim, billing provider, or is unallocated.
      - object
        - `type` 'service_line_by_id', required — Discriminator value: service_line_by_id
        - `value` string, uuid, required
      - object
        - `type` 'claim_by_id', required — Discriminator value: claim_by_id
        - `value` string, uuid, required
      - object
        - `type` 'claim_by_encounter_external_id', required — Discriminator value: claim_by_encounter_external_id
        - `value` string, required
      - object
        - `type` 'billing_provider_by_id', required — Discriminator value: billing_provider_by_id
        - `value` string, uuid, required
      - object
        - `type` 'appointment_by_id_and_patient_external_id', required — Discriminator value: appointment_by_id_and_patient_external_id
        - `appointment_id` string, required
        - `patient_external_id` string, required
      - object
        - `type` 'unattributed', required — Discriminator value: unattributed
    - `earmark` union — If enabled for your organization, defines how a patient prepayment allocation should be earmarked for future auto-allocation. Earmarks hold the allocation until a matching encounter is created, then attempt to allocate to that encounter. Only applicable for unattributed allocations.
      - object — Earmark for auto-allocation to an encounter with this specific date of service
        - `type` 'date_of_service', required — Discriminator value: date_of_service
        - `value` string, required — ISO 8601 date; formatted YYYY-MM-DD (i.e. 2012-02-01)
      - object — Earmark for auto-allocation to an encounter with this specific external ID (more specific than date of service)
        - `type` 'external_encounter_id', required — Discriminator value: external_encounter_id
        - `value` string, required
  - `invoice` string, uuid
  - `refund_reason` 'OVERCHARGED' | 'ENTERED_IN_ERROR' | 'TRANSFER'
  - `allocation_restrictions` TypeFinancialsAllocationRestrictionCreate[] — Optional restrictions constraining which claims this refund's credit can be auto-allocated to (e.g. billing provider NPI). Restriction (type, value) pairs must be unique. When omitted, the refund is unrestricted. Refunds created from an existing payment inherit that payment's restrictions instead.
    - `restriction_type` 'billing_provider_npi' | 'service_facility_id', required — The dimension along which a payment's auto-allocation can be restricted.
    - `restriction_value` string, required — For billing_provider_npi, the NPI. For service_facility_id, the organization service facility ID.
  - `raise_on_overdraft` boolean — If true, the refund will be rejected if it would cause any account to be overdrafted. Defaults to false.

## Response `200`

Response with status 200

- V1PatientRefund — unresolved $ref

## Other responses

- `403` — Error response with status 403
- `404` — Error response with status 404
- `422` — Error response with status 422

---

[API](https://skmtc.net/joincandidhealth/apis/api-reference.md) · [All operations](https://skmtc.net/joincandidhealth/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/joincandidhealth/api-reference/revisions/7cc5974e4128/schema)