Use and settle your VIP tab

Spend against the house tab, read what you owe, and understand the monthly settlement.

Owned by VIP Member · 8 steps · about 15 minutes

VIP MemberOWNER manual → Admin manual →

Why this exists

The tab is the platform's most misunderstood feature, so the design intent matters more than the clicks here.

A tab is not a balance you own — it is a limit on what you may owe. Spending against it does not spend money; it records an obligation on a double-entry ledger. That is why your purchasing power is three separate things: prepaid credit you actually paid in, earned credit from resale you actually made, and tab headroom you have not paid at all. The platform spends them in exactly that order, so the tab is always the last resort.

Settlement is scheduled, not manual. On the first tick of a new month the platform settles the previous month for everyone carrying a balance: it sweeps your prepaid credit first, then charges your card for the remainder, and emails an invoice. A declined card marks the settlement failed and freezes the tab — the balance stays owed, because freezing a tab is a credit decision, not forgiveness.

The ledger behind all of this is append-only, enforced by database triggers. Nothing here is ever edited; corrections are new balanced entries.

Before you start

  • A VIP member session (vip_member implies member, so all member surfaces work too).
  • A tab with a limit — an admin sets it; VIP status alone does not create headroom.

Practise with

PersonaEmailPasswordNote
vip_membervip@club.test vip123the VIP persona for this workflow
adminadmin@club.test admin123sets tab limits and runs settlement

Steps 1–4 — VIP Member

their manual →
  1. 1
    Open your credit page and read the three numbers separately: prepaid, earned, and tab used against the limit.
    /my/credit ledger
    Expected result The balances plus your purchasing power.
    Watch out for Purchasing power adds tab headroom to real money. It is what you can spend, not what you have.
  2. 2
    Look at the same balances as the API returns them, so you can see the fields the pages are built from.
    /api/credit/balance ledger
    Expected result Prepaid, earned, tab used, headroom and status.
  3. 3
    Pay for something with house credit and watch which pot it comes out of.
    /checkout/{order_id} payments
    Expected result Promo is consumed first, then prepaid, then earned, and only then does the tab absorb the remainder.
    Watch out for If the total is more than promo + prepaid + earned + headroom, the payment is refused outright — that sum is `purchasing_power_cents`, and it is the number the refusal is measured against. There is no partial settlement of an order.
  4. 4
    Read your statement as a running story: every top-up, purchase, resale payout and tab movement in order.
    /my/credit/statement ledger
    Expected result A line per ledger movement with a running balance.
    Watch out for Nothing on this statement can be edited or deleted, by anyone. If something is wrong it is corrected with a new compensating entry, which will also appear here.

Steps 5–8 — Admin

their manual →

Sets the tab limit, runs settlement, and reads the ledger it posts to.

  1. 5
    As an admin, set or adjust a VIP's tab limit — or freeze it.
    /api/admin/credit/users/{user_id}/tab PUT ledger
    Expected result The tab row with its new limit or status.
    Watch out for Freezing a tab stops further spending; it does not clear what is owed. Revoking VIP status freezes it automatically for the same reason.
  2. 6
    Open the settlement dashboard and look at last month's run: who settled, who failed, who was waived.
    /admin/tab-settlements ledger
    Expected result One row per user per period, with status.
  3. 7
    Run a settlement for a period manually when you need to — for a retry, or to see the mechanism in a demo.
    /api/admin/tab-settlements/run POST ledger
    Expected result Per-user results: prepaid swept, card charged, invoice emailed.
    Watch out for It is idempotent per user and period. Running it twice does not charge twice — the unique constraint on user plus period is the guard, not the button being greyed out.
  4. 8
    Trace one settlement into the ledger and confirm it balances: every transaction has at least two entries and the debits equal the credits.
    /admin/ledger/transactions ledger
    Expected result The settlement's transaction with its entries.
    Watch out for Try to edit one and the database itself refuses. The append-only trigger is not a UI convention — it fires even from the admin data suite.
Back to the VIP Member manual Understand your points and the exchange →