Brewski tracks reusable container deposits separately from standard order payments. Two new tables underpin this workflow:

• container_returns – one row per return event, capturing quantity, credited amount, and links to the originating order, client, packaging lot, and optionally the individual packaged unit.
• deposit_transactions – ledger of all deposit movements (charge, return, adjustment). Charges increase liability (e.g., positive deposit lines on an order); returns and adjustments decrease it. Rows are keyed by team_id and (optionally) client_id.

POST /returns records a return event and automatically credits the deposit ledger. Order and client endpoints now surface the available credit summary via their deposits payloads. Clients receive the summary as deposits.summary while orders expose deposits (including optional transactions for per-order activity).

Column	Notes
team_id	Owning team, cascades on delete.
client_id	Client associated with the return (nullable).
order_id	The order the container belonged to (nullable).
packaging_lot_id	Links the return back to the original packaging lot (nullable).
container_id	The container definition (keg/cask/etc.).
packaged_unit_id	Optional when the keg was individually tracked; unique when present.
quantity	Decimal quantity returned (kegs, casks, etc.).
amount_minor	Deposit value credited for this return in minor currency units.
recorded_by / recorded_at	Metadata about who captured the return.

Column	Notes
team_id	Ledger partition key.
client_id	When set, contributes to the client’s available credit.
order_id	Optional link back to the originating order.
container_return_id	Present when the row was created from a container return.
source	charge, return, or adjustment.
amount_minor	Signed value (positive = liability, negative = credit).
balance_minor	Optional running balance for future optimisations.
metadata	Free-form JSON to store contextual details (scan IDs, device info, etc.).

When the running balance is negative the team/client has available credit (creditMinor in the aggregated payloads); a positive balance represents outstanding deposit liability. source = "adjustment" entries are generated when deposit credit is applied to an order (for example, passing depositCreditMinor to POST /orders/:id/payments).

• Auth: Bearer token. Caller must belong to the target team.
• Body:

  {
    "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
    "clientId": "5e7f...",            // optional, required to credit the client balance
    "orderId": "709f31fc-9371-4e7b-a41c-0eb4e7d5d7fa", // optional linkage
    "packagedUnitId": "unit-9001...", // use for individually tracked kegs
    "containerId": "4fb3...",         // required when packagedUnitId is omitted
    "quantity": 6,                     // whole number; defaults to 1 when packagedUnitId supplied
    "amountMinor": 15000,              // optional override; defaults to team/client deposit price × quantity
    "note": "Returned via driver manifest",
    "metadata": { "scanner": "rfid-01" }
  }

• Response 201:

  {
    "return": {
      "id": "ret_01R...",
      "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
      "clientId": "5e7f...",
      "orderId": "709f31fc-9371-4e7b-a41c-0eb4e7d5d7fa",
      "packagingLotId": "lot-9041...",
      "containerId": "4fb3...",
      "packagedUnitId": "unit-9001...",
      "quantity": 1,
      "amountMinor": 2500,
      "recordedBy": "user_123",
      "recordedAt": "2025-02-12T10:11:00.000Z",
      "note": "Returned via driver manifest",
      "metadata": { "scanner": "rfid-01" },
      "createdAt": "2025-02-12T10:11:00.000Z",
      "updatedAt": "2025-02-12T10:11:00.000Z"
    },
    "transaction": {
      "id": "dep_01R...",
      "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
      "clientId": "5e7f...",
      "orderId": "709f31fc-9371-4e7b-a41c-0eb4e7d5d7fa",
      "containerReturnId": "ret_01R...",
      "source": "return",
      "amountMinor": -2500,
      "balanceMinor": null,
      "metadata": {
        "quantity": 1,
        "amountPerUnitMinor": 2500,
        "autoCalculated": true,
        "scanner": "rfid-01"
      },
      "createdBy": "user_123",
      "createdAt": "2025-02-12T10:11:00.000Z",
      "updatedAt": "2025-02-12T10:11:00.000Z"
    },
    "depositSummary": {
      "balanceMinor": -2500,
      "creditMinor": 2500,
      "liabilityMinor": 0
    }
  }

• Notes:
• Provide packagedUnitId to mark a specific keg as returned; otherwise supply containerId and quantity for bulk returns.
• Quantities must be whole numbers; when returning tracked units the API automatically forces the quantity to 1.
• If no amountMinor is supplied the API uses the team/client deposit configuration for keg containers.
• depositSummary reflects the client’s updated credit balance after this return.