Skip to main content
Use leave balances when you need the current answer to how much leave a worker has available in a given period.
Balances are derived from leave transactions. Plane refreshes the ledger first, then recomputes the balance snapshot from those transactions.

​
Attributes

​
id
string
Unique identifier for the leave balance, for example lvb_8kPqR2nYx1mVtD.
​
worker
string
ID of the worker this balance belongs to.
​
policy
string | null
Representative leave policy for this balance. Returns null when the balance no longer has a primary policy pointer.
​
type
string
Leave type tracked by this balance.
​
unit
string
Unit used for all numeric values. One of days or hours.
​
period
object
Period window covered by this balance.
​
entitled
number
Total credited leave for the period from accrual and adjustment transactions.
​
used
number
Leave already used, based on past usage and reversal transactions.
​
scheduled
number
Approved leave scheduled for future dates in the period.
​
available
number
Current net available balance.
​
carried
number
Net carried amount, including carryover, expiry, forfeit, and payout effects.
​
created
string
ISO 8601 timestamp of when the balance was created.
​
updated
string
ISO 8601 timestamp of the most recent refresh of the balance.
{
  "id": "lvb_8kPqR2nYx1mVtD",
  "worker": "wr_CgcLakmx4guire",
  "policy": "lvp_Xk9mPq2vR8tn3e",
  "type": "vacation",
  "unit": "days",
  "period": {
    "starts": "2026-01-01",
    "ends": "2026-12-31"
  },
  "entitled": "25.0",
  "used": "5.5",
  "scheduled": "2.5",
  "available": "17.0",
  "carried": "0.0",
  "created": "2026-01-01T00:00:00Z",
  "updated": "2026-03-12T08:00:00Z"
}