# Transactions

> Bank transactions: list them, reconcile them one at a time or in bulk, and reverse a reconciliation.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List bank transactions

`GET /api/public/v1/entities/{entityId}/transactions`

SDK: `prosaic.transactions.list(entityId, params)`

Returns paginated bank transactions for the specified entity with optional date range filtering. By default, transactions dated before the entity's conversion date are hidden, matching the app, and a dateFrom earlier than the conversion date is moved up to it. Pass `includePreConversion=true` to see them. Requires API key authentication and entity access.

### Path parameters

- `entityId` (string, required)

### Query parameters

- `page` (integer): Page number (starts at 1) Default: `1`.
- `pageSize` (integer): Number of items per page. Default: `20`.
- `dateFrom` (string, date): Start date for filtering transactions (ISO 8601 format)
- `dateTo` (string, date): End date for filtering transactions (ISO 8601 format)
- `includePreConversion` (string): Include transactions dated before the entity's conversion date (default false) One of: `true`, `false`.
- `journalId` (string, uuid): Filter by journal ID to get transactions reconciled to a specific journal.
- `reconciliationStatus` (string): Filter by reconciliation status. One of: `reconciled`, `unreconciled`.
- `view` (string): `full` (default) returns each transaction with its bank account, linked GL account, user, merchant, category and suggestions in full. `compact` returns what coding needs: the transaction's own fields, the bank account's id and name, merchant and category names, the reconciliation status, and each suggestion's source, confidence, rule name and lines as account code, account name, tax code, proportion, debit and credit. . One of: `full`, `compact`. Default: `"full"`.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Bad request - missing or invalid parameters
  - `error` (string)
  - `code` (string)
  - `field` (string)
  - `value` (string)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const page = await prosaic.transactions.list(entityId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/transactions \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Reconcile bank transactions (bulk or single)

`POST /api/public/v1/transactions/reconcile`

SDK: `prosaic.transactions.reconcileBulk(params)`

Reconciles one or more bank transactions by creating journal entries with automatic tax calculations.
All requests are processed asynchronously via background jobs.

#### Processing

- All transactions are queued for background processing
- Returns `requestId` for tracking
- Transactions are grouped by entity automatically
- Separate jobs created per entity for parallel processing

#### Entity Determination

Unlike other endpoints, this endpoint does **not** require an `entityId` in the path.
Instead, entities are determined from the transactions themselves:
- Each transaction is associated with a bank account
- Each bank account belongs to an entity
- Transactions can span multiple entities (separate jobs per entity)

#### Tax Handling

The system supports three tax modes:

#### NO_TAX
- No tax calculations are performed
- Assignment amounts are used as-is in journal entries
- Use for transfers between accounts or tax-exempt transactions

#### TAX_INCLUSIVE (Default for NZ)
- Assignment amounts **include** tax
- System automatically splits the amount into base and tax components
- **Formula**: `baseAmount = amount / (1 + rate)`, `taxAmount = amount - baseAmount`
- **Example**: $115 with GST 15% → $100 base + $15 GST
- Common for expenses where you know the total paid (including GST)

#### TAX_EXCLUSIVE
- Assignment amounts **exclude** tax
- System adds tax on top of the specified amount
- **Formula**: `taxAmount = amount × rate`, `totalAmount = amount + taxAmount`
- **Example**: $1000 with GST 15% → $1000 base + $150 GST = $1150 total
- Common for income where you invoice a base amount plus GST

#### Important Notes

- Maximum 500 transactions per request
- Each transaction amount must equal the sum of its assignment debits/credits
- Each assignment line requires a valid `taxCode` from the entity's tax rates
- Generated tax lines are automatically created and linked to parent lines
- Transactions already being processed will return a 409 conflict error

### Request body

Content type: `application/json`

- `updates` (array of objects, required)
  - `id` (string, required)
  - `invoiceId` (string)
  - `invoiceAllocations` (array of objects)
    - `invoiceId` (string, required)
    - `amount` (number, required)
  - `billAllocations` (array of objects)
    - `billId` (string, required)
    - `amount` (number, required)
  - `refundCredit` (object)
    - `contactId` (string, required)
  - `creditHolding` (object)
    - `accountCode` (string, required)
    - `taxCode` (string, required)
  - `fixedAssetDisposal` (object)
    - `fixedAssetId` (string, required)
    - `reverseLaterDepreciation` (boolean)
    - `saleTaxCode` (string)
    - `accountCodes` (object)
      - `loss` (string)
      - `gain` (string)
      - `private_loss` (string)
      - `private_gain` (string)
      - `depreciation_recovery` (string)
      - `capital_gain` (string)
  - `fixedAssetPurchase` (object)
    - `name` (string, required)
    - `entityFixedAssetTypeId` (string, required)
    - `startDate` (string, required)
    - `depreciationMethod` (string, required)
    - `assetNumber` (string)
    - `businessUsePercentage` (number)
    - `taxCode` (string)
    - `depreciationRate` (number)
    - `usefulLifeYears` (number)
  - `narration` (string)
  - `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`.
  - `fileIds` (array of strings)
  - `destinationEntityId` (string)
  - `assignment` (array of objects)
    - `code` (string, required)
    - `name` (string, required)
    - `taxCode` (string, required)
    - `credit` (number)
    - `debit` (number)
    - `description` (string)
    - `destinationEntityId` (string)
    - `dimensionOptionIds` (array of strings)

### Responses

- `200`: Successful response
  - `success` (boolean, required): One of: `true`.
  - `data` (object, required)
    - `requestId` (string, required)
    - `transactionIds` (array of strings, required)
    - `status` (string, required)
    - `entityJobs` (array of objects, required)
      - `entityId` (string, required)
      - `jobId` (string, required)
      - `transactionCount` (number, required)
  - `message` (string, required)
- `400`: Bad request - validation error
  - `error` (string)
  - `code` (string)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `404`: Transaction(s) not found, already reconciled, or access denied
  - `error` (string)
  - `code` (string)
- `409`: Conflict - transactions already being processed
  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.transactions.reconcileBulk({
  updates: [
    {
      id: 'ID',
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/transactions/reconcile \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "id": "ID"
      }
    ]
  }'
```

## Reconcile a bank transaction

`POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reconcile`

SDK: `prosaic.transactions.reconcile(entityId, transactionId, params)`

Reconciles a single bank transaction by creating journal entries with automatic tax calculations.

#### Tax Handling

The system supports three tax modes:

#### NO_TAX
- No tax calculations are performed
- Assignment amounts are used as-is in journal entries
- Use for transfers between accounts or tax-exempt transactions

#### TAX_INCLUSIVE (Default for NZ)
- Assignment amounts **include** tax
- System automatically splits the amount into base and tax components
- **Formula**: `baseAmount = amount / (1 + rate)`, `taxAmount = amount - baseAmount`
- **Example**: $115 with GST 15% → $100 base + $15 GST
- Common for expenses where you know the total paid (including GST)

#### TAX_EXCLUSIVE
- Assignment amounts **exclude** tax
- System adds tax on top of the specified amount
- **Formula**: `taxAmount = amount × rate`, `totalAmount = amount + taxAmount`
- **Example**: $1000 with GST 15% → $1000 base + $150 GST = $1150 total
- Common for income where you invoice a base amount plus GST

#### Prerequisites — Finding Tax Codes and Account Codes

Before reconciling, you need two pieces of information:

- **Account codes**: Retrieve the entity's chart of accounts via `GET /api/public/v1/entities/{entityId}/charts`. Use the `code` field (e.g., "2030") in the assignment `code` field below.
- **Tax codes**: Retrieve the entity's tax rates via `GET /api/public/v1/entities` (filter by `entityId`). The `taxRates[].code` field (e.g., "GST15", "EXEMPT", "ZERO") is used in the assignment `taxCode` field below.

#### Integration Flow

1. **GET `/entities`** - Retrieve entity with available `taxRates[]`
2. **GET `/entities/{entityId}/transactions`** - List unreconciled transactions
3. **POST `/entities/{entityId}/transactions/{transactionId}/reconcile`** - Reconcile with:
   - Select appropriate account (from entity's chart of accounts)
   - Select tax rate using `taxCode` from step 1
   - Specify `taxMode` based on whether your amounts include/exclude tax
4. System validates and creates journal entries with tax lines automatically

#### Important Notes

- The transaction amount must equal the sum of assignment debits/credits
- Each assignment line requires a valid `taxCode` from the entity's tax rates
- Generated tax lines are automatically created and linked to parent lines
- Use the entity's `defaultTaxAccountId` (GST account) for tax collection/payment

### Path parameters

- `entityId` (string, required)
- `transactionId` (string, required)

### Request body

Content type: `application/json`

- `assignment` (array of objects, required)
  - `code` (string, required)
  - `name` (string, required)
  - `taxCode` (string, required)
  - `credit` (number)
  - `debit` (number)
  - `description` (string)
  - `dimensionOptionIds` (array of strings)
- `narration` (string)
- `taxMode` (string): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`.
- `fileIds` (array of strings)

### Responses

- `200`: Successful response
  - `success` (boolean, required): One of: `true`.
  - `data` (object, required)
    - `transactionId` (string, required)
    - `journalId` (string, required)
    - `logicalJournalId` (string, required)
- `400`: Bad request - validation error or missing/invalid system account setup (SYSTEM_ACCOUNT_VALIDATION).
  - `error` (string)
  - `code` (string)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)
- `404`: Transaction not found or already reconciled
  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.transactions.reconcile(entityId, transactionId, {
  assignment: [
    {
      code: '200',
      name: 'Example Ltd',
      taxCode: 'TAX_CODE',
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/transactions/$TRANSACTION_ID/reconcile \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assignment": [
      {
        "code": "200",
        "name": "Example Ltd",
        "taxCode": "TAX_CODE"
      }
    ]
  }'
```

## Reverse a bank transaction reconciliation

`POST /api/public/v1/entities/{entityId}/transactions/{transactionId}/reverse`

SDK: `prosaic.transactions.reverse(entityId, transactionId, params)`

Reverses a previously reconciled bank transaction, making it available for reconciliation again.

#### Business Rules

- Only reconciled transactions can be reversed
- Only bank reconciliation journals (AUTOMATIC type) can be reversed
- The journal must be in POSTED status
- The transaction must belong to the specified entity

#### What Happens During Reversal

1. Creates a reversal journal entry that negates the original reconciliation
2. Updates the reconciliation status to REVERSED
3. Makes the bank transaction available for reconciliation again
4. Maintains full audit trail of the reversal

#### Integration Flow

1. **GET `/entities/{entityId}/transactions`** - Find reconciled transactions to reverse
2. **POST `/entities/{entityId}/transactions/{transactionId}/reverse`** - Reverse the reconciliation
3. The transaction becomes available for new reconciliation via the reconcile endpoint

### Path parameters

- `entityId` (string, required)
- `transactionId` (string, required)

### Request body

Content type: `application/json`

- `reverseReason` (string)

### Responses

- `200`: Successful response
  - `success` (boolean, required): One of: `true`.
  - `data` (object, required)
    - `transactionId` (string, required)
    - `logicalJournalId` (string, required)
    - `reversalJournalId` (string, required)
    - `reversedAt` (string, date-time, required)
    - `reverseReason` (string, required)
- `400`: Bad request - validation error or transaction cannot be reversed
  - `error` (string)
  - `code` (string)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)
- `404`: Transaction not found or access denied
  - `error` (string)
  - `code` (string)
- `409`: The receipt can't be unmatched because some of its credit was refunded
(`PAYMENT_REFUNDED`). Unmatch the refund first.

  - `error` (string)
  - `code` (string)
- `500`: Internal server error
  - `error` (string)
  - `code` (string)

### Example (Node SDK)

```ts
const { data } = await prosaic.transactions.reverse(entityId, transactionId, {
  reverseReason: 'string',
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/transactions/$TRANSACTION_ID/reverse \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reverseReason": "string"
  }'
```