# Adjustment Transactions V1 — Developer Guide

> **Reference:** [Adjustment Transactions (V1) Endpoint Documentation](https://papidocs.hs1api.com/publicapi/api-financial-management/adjustment-transactions-(v1))


Adjustment transactions represent ledger entries that modify a patient's balance. **Bulk list and get-by-id** responses can include every ledger type the API treats as part of the adjustments domain, not only “base” charge or credit rows. Narrow results with `?filter=ledgerType==...` when you need a single family.

Common primary types:

| `ledgerType` | Description |
|  --- | --- |
| `PatientChargeAdjustment` | Reduces or offsets a procedure charge on the patient ledger |
| `PatientCreditAdjustment` | Applies a credit to the patient's account, optionally distributed to specific charges |


**Also returned** (same endpoints), depending on data and filters:

| `ledgerType` | Typical role |
|  --- | --- |
| `PatientChargeAdjustmentRebill` | Replacement row after a charge adjustment correction |
| `PatientChargeAdjustmentCancellation` | Cancellation row for a superseded charge adjustment |
| `PatientCreditAdjustmentRebill` | Replacement row after a credit adjustment correction |
| `PatientCreditAdjustmentCancellation` | Cancellation row for a superseded credit adjustment |
| `InsuranceRefundAdjustment` | Insurance-side refund / offset (often tied to claim payment flows) |
| `InsuranceRefundAdjustmentRebill` / `InsuranceRefundAdjustmentCancellation` | Rebill or cancellation variants |
| `PatientCreditCardVoid` / `PatientCreditCardRefund` | Card-related ledger rows grouped with adjustments in this API surface |


> **Published OpenAPI:** The bundled Swagger specification for `/v1/transactions/adjustments` documents **GET** (bulk list and get-by-id) only. This guide matches that surface.


## GET — Bulk List Adjustment Transactions

Returns a paginated list of adjustment transaction entries filtered by the provided criteria.

> **⚠️ Rate Limited:** This endpoint is rate limited. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting) for details.


### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `Organization-ID` | header | Yes | string | The organization ID |
| `filter` | query | Yes | string | Filter criteria (see filter keys below) |
| `responseFields` | query | No | string | Comma-delimited list of fields to include, or `ALL` |
| `page` | query | No | string | Page number for pagination |
| `pageSize` | query | No | string | Number of records per page |
| `lastId` | query | No | string | Largest patient ledger ID from the previous page; use with date-oriented filters for stable pagination |


### Bulk list rules (filters and pagination)

These rules match the published OpenAPI for this resource and the API’s bulk-list validation:

- **Valid `filter` required:** Every bulk list request must include a non-empty `filter`. Requests with no filter, an empty filter, or a filter with an empty value (for example `ledgerType==` with no value) receive **405 Method Not Allowed**.
- **`page` / `pageSize`:** If you use pagination query parameters, a valid `filter` is still required. Sending `page` and/or `pageSize` without a proper filter can return **405**.
- **Date filters and `lastId`:** When filtering by dates (for example `lastModified`), combine with `lastId` to walk pages in ID order; this is the recommended pattern for large result sets.
- **Default date window:** If you omit a date-limiting filter such as `lastModified`, the service may apply a default date constraint for this endpoint (exact default can vary by release).
- **`location.id`:** You can request all locations with `location.id==ALL` or `location.id==*`, or list form such as `location.id->["ALL"]`. For a transitional period, **omitting** `location.id` may default to all locations; this may later become a required filter.


### Filter Keys

Filters use `?filter=key==value`, `?filter=key>=value`, etc. Combine predicates with commas. Use real `ledgerType` enum strings (examples below), not generic placeholders.

| Filter Key | Operators | Example |
|  --- | --- | --- |
| `id` | `->` (in list) | `?filter=id->[123,124]` |
| `patient.id` | `==`, `->` | `?filter=patient.id==789` or `?filter=patient.id->[789,790]` |
| `provider.id` | `==` | `?filter=provider.id==456` |
| `ledgerType` | `==`, `!=` | `?filter=ledgerType==PatientChargeAdjustment` or `?filter=ledgerType!=PatientCreditAdjustment` |
| `transactionDate` | `>`, `<`, `>=`, `<=` | `?filter=transactionDate>=2025-01-01` |
| `location.id` | `==`, `!=`, `->` | `?filter=location.id==123`, `?filter=location.id==ALL`, `?filter=location.id!=456`, or `?filter=location.id->["ALL"]` |
| `lastModified` | `>`, `<`, `>=`, `<=` | `?filter=lastModified>=2025-01-01` |


### Example Requests

Fetch all charge adjustments for a patient:

```
GET /api/v1/transactions/adjustments?filter=patient.id==12000006542062,ledgerType==PatientChargeAdjustment
```

Fetch all adjustments modified since a date:

```
GET /api/v1/transactions/adjustments?filter=lastModified>=2025-01-01,location.id==ALL
```

## GET — Adjustment Transaction by ID

### Parameters

| Parameter | In | Required | Type | Description |
|  --- | --- | --- | --- | --- |
| `transactionId` | path | Yes | integer | The ID of the adjustment transaction |
| `Organization-ID` | header | Yes | string | The organization ID |
| `responseFields` | query | No | string | Comma-delimited list of fields to include, or `ALL` |


### Example Request

```
GET /api/v1/transactions/adjustments/100000042301
```

## Streaming

Adjustment transactions are streamable via the [Streaming API](https://papidocs.hs1api.com/publicapi/api-consumer-guide#streaming). Events are published under the `TransactionV1` domain type.

### Routing Key Format

```
organizationId.locationId.TransactionV1.operationType
```

### Example Routing Keys

Listen for all adjustment events across all locations:

```
66d22762060811049b50d085.*.TransactionV1.*
```

Listen for stream `CREATE` events only:

```
66d22762060811049b50d085.*.TransactionV1.CREATE
```

### Operations Emitted (stream)

| `ledgerType` (examples) | `CREATE` | `UPDATE` | `DELETE` |
|  --- | --- | --- | --- |
| `PatientChargeAdjustment` | Yes — e.g. new adjustment or correction (replacement record) | Yes — e.g. in-place update | Yes — e.g. when removed and cancellation flow emits delete for prior row |
| `PatientCreditAdjustment` | Yes — e.g. new adjustment or correction | Yes — e.g. in-place update | Yes — e.g. when removed |


> **Filtering by `ledgerType`:** All transaction sub-types share the `TransactionV1` domain. Use the `ledgerType` field in the event payload to identify adjustment-related events. Cancellation and rebill rows use their own `ledgerType` values.


> **Corrections and cancellations:** When a correction or delete flow creates a cancellation or replacement row, the stream often emits **`CREATE`** for the new row (for example a `*Cancellation` or `*Rebill` `ledgerType`). The superseded row may also emit **`DELETE`** on the stream in some paths. Behavior is implementation-specific; always inspect `ledgerType`, `isActive`, and replacement links in the payload.


## Response Structure

A successful **GET** returns `200` with:

| Field | Type | Description |
|  --- | --- | --- |
| `data` | object or array | The adjustment transaction, or a page of transactions |
| `warnings` | array | Non-fatal warnings |
| `errors` | array | Field-level or request errors when applicable |


For bulk GET, `data` is an array and includes `meta.pagination`.

### `data` Object — Adjustment Transaction Fields

| Field | Type | Read-Only | Description |
|  --- | --- | --- | --- |
| `id` | integer | Yes | Unique transaction ID |
| `type` | string | Yes | Always `"Transaction"` |
| `ledgerType` | string | Yes | Ledger discriminator (see intro) |
| `amount` | number | No | Transaction amount |
| `ownership` | string | No | `PATIENT` or `GUARANTOR` |
| `transactionDate` | string (date) | No | `YYYY-MM-DD` |
| `entryDate` | string (date-time) | Yes | Creation timestamp |
| `lastModified` | string (date-time) | Yes | Last modification timestamp |
| `isAutomaticallyPosted` | boolean | Yes | System-posted flag |
| `isActive` | boolean | Yes | Active/cancelled status |
| `note` | string | No | Free-text note |
| `previousTransaction` | object | Yes | Ref to replaced record if this is a rebill |
| `replacedByTransaction` | object | Yes | Ref to rebill if this record was replaced |
| `patient` | object | — | `{ id }` |
| `location` | object | — | `{ id }` |
| `provider` | object | — | `{ id }` (charge adjustments only) |
| `organizationLedgerType` | object | — | `{ id }` |
| `patientProcedure` | object | Yes | `{ id }` (read-only) |
| `insuranceClaim` | object | Yes | `{ id }` (read-only) |
| `insurancePayment` | object | Yes | `{ id }` (read-only) |
| `patientPaymentTransaction` | object | — | `{ id }` (charge adjustments — COLLECTION link) |
| `transactionTags` | object | — | `{ orderIndex: { id } }` |
| `reasonTags` | object | — | `{ orderIndex: { id } }` (credit adjustments) |
| `distributions` | array | — | `[{ chargeId, appliedAmount, isActive }]` (credit adjustments) |


## Errors & Warnings Reference

details
summary
strong
HTTP Status Code Errors
— click to expand
#### `400` — Bad Request

The request parameters or filter are invalid or cannot be processed.

#### `405` — Method Not Allowed

|  |  |
|  --- | --- |
| **Message** | Method Not Allowed (bulk list constraints). |
| **Why** | The bulk list route requires a valid `filter`. Common cases: missing or empty `filter`, empty filter value (for example `ledgerType==` with nothing after `==`), or using `page` / `pageSize` without a valid filter. |
| **Fix** | Always send a non-empty `filter` that matches the supported keys and operators. Add a date-oriented filter and use `lastId` for paging when listing large windows. |


#### `401` — Unauthorized

|  |  |
|  --- | --- |
| **Message** | Authentication is required and has failed or has not been provided. |
| **Why** | Missing, expired, or malformed Bearer token. |
| **Fix** | Provide a valid Bearer token in the `Authorization` header. |


#### `403` — Forbidden

|  |  |
|  --- | --- |
| **Message** | The request is understood, but it has been refused or access is not allowed. |
| **Why** | The caller is not permitted to read adjustment transactions for this organization. |
| **Fix** | Confirm credentials and organization access with your integration administrator. |


#### `404` — Not Found

|  |  |
|  --- | --- |
| **Message** | The requested resource is either missing or does not exist. |
| **Why** | No adjustment transaction exists for the given ID within your organization. |
| **Fix** | Confirm the `transactionId` is correct and belongs to your organization. |


#### `408` — Request Timeout

|  |  |
|  --- | --- |
| **Message** | The server timed out while processing the request. |
| **Why** | High server load or overly broad filter. |
| **Fix** | Narrow filter criteria and retry. |


#### `429` — Too Many Requests

|  |  |
|  --- | --- |
| **Message** | Rate limit exceeded. |
| **Why** | Too many requests in a short period. |
| **Fix** | Implement exponential backoff. See the [rate limiting guide](https://papidocs.hs1api.com/publicapi/api-consumer-guide#rate-limiting). |


#### `500` — Internal Server Error

|  |  |
|  --- | --- |
| **Message** | An unexpected error occurred. |
| **Fix** | Retry. If the issue persists, contact support with the request details and timestamp. |