# 0.15.9 Migration Guide

Migration guide for upgrading to Blnk v0.15.9, covering post-transaction hooks for rejected transactions, queued create errors, atomic bulk rollback, monitor updates, split validation, and balance history.

This guide covers the changes you need to review when upgrading to Blnk v0.15.9.

Review this guide before you upgrade if your app uses `POST_TRANSACTION` hooks, creates queued or bulk transactions, matches bulk failure messages, or reads historical balances. Each section links to the Core 0.15.9 code or test that shows the behavior.

## At a glance

| Change | Who is affected? | What changed |
| :-- | :-- | :-- |
| Database migrations | Everyone | Two migrations run with `blnk migrate up`. |
| Hooks for rejected transactions | Apps with `POST_TRANSACTION` hooks | Hooks now also run when a transaction is rejected. |
| Queued create errors | Apps that create queued transactions | A used reference or unknown balance now returns an error instead of `201`. |
| Atomic bulk rollback | Apps that send atomic bulk requests | Queued atomic batches now roll back when a worker rejects an item. Handle the new batch failure event idempotently. |
| Monitor updates | Apps that update balance monitors | A PUT changes only the fields you send. |
| Negative split distributions | Apps that send split transactions | A negative distribution is rejected. |
| Balance history | Apps that read historical balances | Backdated transactions are now counted correctly. |

## Database migrations

0.15.9 adds a column that balance history uses, and drops four database triggers that Blnk no longer uses.

**What to do:**

1. Pause transaction submissions and let queued jobs finish.
2. Stop the old API and every old worker. A 0.15.8 worker does not check whether a queued atomic batch has failed, so it can apply items that 0.15.9 would reject.
3. Back up the database and run `blnk migrate up`. The bundled Docker Compose file runs it on start.
4. Start the 0.15.9 API and workers.

The trigger migration sets a 3-second lock timeout so it fails instead of blocking writes. If it times out, wait for long-running queries to finish and run it again.

Both migrations have down steps. The trigger down step recreates the triggers. The snapshot down step drops `last_tx_seq`, so snapshots taken on 0.15.9 lose it. Test a rollback on a copy of your database first.

## Hooks for rejected transactions

From 0.15.9, a rejected transaction calls your `POST_TRANSACTION` hooks. `data.status` is `REJECTED`, and `data.meta_data.blnk_rejection_reason` says why.

```json Rejected transaction hook (shortened) {5,7} wrap
{
  "transaction_id": "txn_aa13b549-c278-47ee-87d7-2e2cfcad99ce",
  "hook_type": "POST_TRANSACTION",
  "data": {
    "status": "REJECTED",
    "meta_data": {
      "blnk_rejection_reason": "failed to apply transaction to balances: insufficient funds in source balance"
    }
  }
}
```

**What to do:** Check `data.status` before your hook acts on the call. See [Transaction hooks](/webhooks/transaction-hooks).

## Queued create errors

Blnk now saves a queued transaction before it answers. A used reference returns `409 TXN_DUPLICATE_REFERENCE`, and an unknown balance returns `404 BAL_NOT_FOUND`. Before, both returned `201` and the transaction was never recorded.

What is saved depends on the request:

| Request | What Blnk keeps after the error |
| :-- | :-- |
| Single transaction | Nothing. The new attempt has no transaction or `REJECTED` record. On `409`, the original transaction with that reference is unchanged. |
| Bulk request | The items before the failing one. They were already queued and still process, even with `atomic: true`. Items after it are not saved. |
| Split transaction | The legs before the failing one, saved as `QUEUED`. Queue recovery picks up `QUEUED` rows after about 2 hours and can apply them. |

**What to do:** On `409`, look up the original reference instead of retrying. On `404`, fix the balance ID before retrying. After a failed bulk request or split, check each reference before you resend anything. See [Reconcile a queued batch after a duplicate reference](/transactions/bulk-transactions#reconcile-a-queued-batch-after-a-duplicate-reference).

## Atomic bulk rollback

From 0.15.9, when a worker rejects an item in a queued `atomic: true` batch, Blnk refunds applied items or voids inflight items and emits one `bulk_transaction.failed` event for the batch. Blnk records the items still waiting in the queue as `REJECTED` when it reaches them. Before, only `skip_queue: true` rolled back.

If Blnk finds a duplicate reference while adding items to the queue, items already queued may still process, even in an atomic batch. Reconcile by batch ID and reference before resubmitting any items. See [Reconcile a queued batch after a duplicate reference](/transactions/bulk-transactions#reconcile-a-queued-batch-after-a-duplicate-reference).

The failure message now says how many items were refunded, instead of `All transactions in this batch have been refunded`.

**What to do:** Listen for `bulk_transaction.failed` and deduplicate it on `data.batch_id`. Blnk queues one event per batch, but webhook delivery can repeat. If your code matches the old message text, match the event instead. See [Bulk transactions](/transactions/bulk-transactions#webhook-notifications).

## Monitor updates

From 0.15.9, `PUT /balance-monitors/{monitor_id}` changes only the fields you send. A partial body used to fail with `500`.

**What to do:** If your app sends `precision` without `value`, include `value` in the same request to change the scale. If your app does not send `precision` alone, no change is required. See [Update balance monitor](/reference/edit-balance-monitor).

## Negative split distributions

A negative `distribution` used to be accepted, and the `"left"` leg received the difference. From 0.15.9, negative `distribution` and `precise_distribution` values return `400 TXN_VALIDATION_ERROR`; no balance moves.

**What to do:** Send `0` or a positive value for each leg. See [Split transactions](/transactions/split-transactions#distribution).

## Balance history

Balance history could miss a backdated transaction or count a future-dated one twice. From 0.15.9, each transaction is counted once, at its `effective_date`.

Snapshots taken before the upgrade are skipped until new ones replace them. `from_source=true` results do not change.

**What to do:** Expect some past balances to change. If you store history results, read them again, and take a snapshot after you upgrade. See [Historical balances](/balances/historical-balances#how-it-works).

## Core release references

- [Queued atomic rollback and final item states](https://github.com/blnkfinance/blnk/blob/v0.15.9/cmd/workers_lifecycle_test.go#L125-L276), [worker rollback event timing](https://github.com/blnkfinance/blnk/blob/v0.15.9/cmd/workers_lifecycle_test.go#L484-L548), and [the enqueue loop that stops at the first failure](https://github.com/blnkfinance/blnk/blob/v0.15.9/transaction_bulk.go#L51-L75).
- [Queued create status and record tests](https://github.com/blnkfinance/blnk/blob/v0.15.9/api/transaction_queue_durability_test.go#L43-L86), [split legs saved one by one](https://github.com/blnkfinance/blnk/blob/v0.15.9/transaction_queue.go#L339-L360), and [queue recovery of stuck `QUEUED` rows](https://github.com/blnkfinance/blnk/blob/v0.15.9/queue_recovery.go#L53-L64).
- [Rejected transaction hook test](https://github.com/blnkfinance/blnk/blob/v0.15.9/transaction_rejection_test.go#L35-L108).
- [Precision-only monitor update test](https://github.com/blnkfinance/blnk/blob/v0.15.9/api/balance_monitor_defects_e2e_test.go#L384-L411) and [negative split validation test](https://github.com/blnkfinance/blnk/blob/v0.15.9/api/model/model_test.go#L523-L544).
- [Historical balances with legacy snapshots, backdated transactions, and future-dated transactions](https://github.com/blnkfinance/blnk/blob/v0.15.9/database/balance_at_time_snapshot_seq_test.go#L107-L175).
- [Snapshot migration SQL](https://github.com/blnkfinance/blnk/blob/v0.15.9/sql/1793212597.sql) and [trigger migration SQL](https://github.com/blnkfinance/blnk/blob/v0.15.9/sql/1793890679.sql). The [release CI test run](https://github.com/blnkfinance/blnk/actions/runs/43839589650/job/133204642809) applied the migrations and passed these Core tests.

<RelatedTopics
  items={[
    { title: "Upgrade Core", href: "/migrations/core/upgrade" },
    { title: "Blnk Core changelog", href: "/changelog/blnk-core" },
    { title: "Transaction hooks", href: "/webhooks/transaction-hooks" },
    { title: "Bulk transactions", href: "/transactions/bulk-transactions" },
    { title: "Historical balances", href: "/balances/historical-balances" },
  ]}
/>