API reference

Recurring

get/v1/recurring

List recurring charges

recurring.listread tokenidempotent

Every subscription, bill and recurring income the detector finds in the last two years or so of transactions, including the ones the household dismissed or cancelled (see status and activity). The monthly total the app shows is the sum of monthly_cost over the expenses that are neither dismissed nor ended.

Parameters

limit integer · query	Page size, 1–200.
cursor string \| null · query	The `next_cursor` of the previous page.
direction string \| null · query	Only bills and subscriptions (`expense`) or only income (`income`).
X-Organization-Id string \| null · header

Returns 200 · RecurringChargeList

data array of RecurringCharge · required
has_more boolean · required
next_cursor string \| null · required

Example

curl -X GET "https://api.lumaledger.app/v1/recurring" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

get/v1/recurring/calendar

Get the bill calendar

recurring.calendarread tokenidempotent

Every transaction between start and end, marked when it belongs to a recurring charge, plus every recurring charge and income projected onto the days it is expected. Dismissed and cancelled charges are not projected.

Parameters

start date · query · required	The first day.
end date · query · required	The last day. At most 93 days after `start`.
X-Organization-Id string \| null · header

Returns 200 · RecurringCalendarOut

end date · required
items array of CalendarItem · required	By day; within a day, seen before expected and income first.
start date · required
today date · required	The server's today, which `overdue` and `projected` are read against.
totals CalendarTotals · required

Example

curl -X GET "https://api.lumaledger.app/v1/recurring/calendar" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

post/v1/recurring/declare

Declare a recurring charge

recurring.declarewrite tokenidempotent

Say that a merchant bills (or pays) on a cadence: for a yearly renewal with one charge behind it, which the detector cannot see yet, or to correct a cadence it measured wrong. Declaring also confirms the charge. The merchant must have at least one transaction in the ledger.

Parameters

X-Organization-Id

string | null · header

Body · RecurringDeclaration

cadence string · required	One of `weekly`, `biweekly`, `four_weekly`, `monthly`, `quarterly`, `yearly`. Pattern: `^(weekly\|biweekly\|four_weekly\|monthly\|quarterly\|yearly)$`.
merchant string · required	Who is paid (or pays), as a transaction's description names them, or a `merchant_key`. A unique part of the name is enough.

Returns 200 · RecurringCharge

activity string · required	What the charges say: `active`, `missed` (late) or `ended`. A cancelled charge is always `ended`.
amount Money · required	The usual amount of one charge. Always positive.
cadence string · required	One of `weekly`, `biweekly`, `four_weekly`, `monthly`, `quarterly`, `yearly`.
cancel_guide CancelGuide \| null · required	How to cancel it, when LumaLedger knows the merchant. Expenses only.
confidence string · required	`high` (seen enough times to be sure) or `likely` (a regular pattern seen fewer times).
declared_cadence boolean · required	The cadence was declared by the household, not measured.
direction string · required	`expense` (a bill, a subscription) or `income` (a paycheck).
ended_on date \| null · required	When it stopped: the cancellation date given, else the last charge. Null while it is running.
first_date date · required
last_amount Money · required
last_date date · required
merchant_key string · required	The charge's stable key: the merchant or payer it groups by. Pass it to `recurring.set_status`.
monthly_cost Money · required	What it comes to per month at its cadence.
name string · required	The name the charge appears under.
next_expected date · required
occurrences integer · required	How many charges were seen.
previous_amount Money · required	The usual amount before the latest charge.
price_changed boolean · required	The latest charge differs from the usual amount.
status string · required	The household's verdict: `detected` (none given), `confirmed`, `dismissed` (not a recurring charge) or `cancelled`.

Example

curl -X POST "https://api.lumaledger.app/v1/recurring/declare" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cadence": "…",
    "merchant": "…"
  }'

get/v1/recurring/forecast

Forecast recurring bills

recurring.forecastread tokenidempotent

What the recurring charges and income will come to month by month, from today to the end of the horizon: the yearly bills a monthly view never shows, before they land.

Parameters

horizon string · query	`quarter` (3 months) or `year` (12).
X-Organization-Id string \| null · header

Returns 200 · BillForecast

biggest array of ForecastOccurrence · required	The largest expected bills, each once, on the day it lands next.
charges array of ForecastCharge · required	Bills first, costliest first, then income.
end date · required
expected_in Money · required
expected_out Money · required
horizon string · required	`quarter` or `year`.
monthly_out Money · required	`expected_out` per month over the horizon.
months array of ForecastMonth · required
net Money · required
start date · required
today date · required

Example

curl -X GET "https://api.lumaledger.app/v1/recurring/forecast" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN"

post/v1/recurring/status

Set a recurring charge's status

recurring.set_statuswrite tokenidempotent

Give the household's verdict on a recurring charge: confirm it, dismiss it as not recurring, or mark it cancelled (from ended_on). detected forgets the verdict but keeps a declared cadence. Returns the charge as it now reads.

Parameters

X-Organization-Id

string | null · header

Body · RecurringStatusUpdate

ended_on date \| null	With `cancelled`: the day it ended. Defaults to today.
merchant_key string · required	The charge, from `recurring.list`.
status string · required	`confirmed`, `dismissed` (not a recurring charge), `cancelled`, or `detected` to forget the verdict. Pattern: `^(confirmed\|dismissed\|cancelled\|detected)$`.

Returns 200 · RecurringCharge

activity string · required	What the charges say: `active`, `missed` (late) or `ended`. A cancelled charge is always `ended`.
amount Money · required	The usual amount of one charge. Always positive.
cadence string · required	One of `weekly`, `biweekly`, `four_weekly`, `monthly`, `quarterly`, `yearly`.
cancel_guide CancelGuide \| null · required	How to cancel it, when LumaLedger knows the merchant. Expenses only.
confidence string · required	`high` (seen enough times to be sure) or `likely` (a regular pattern seen fewer times).
declared_cadence boolean · required	The cadence was declared by the household, not measured.
direction string · required	`expense` (a bill, a subscription) or `income` (a paycheck).
ended_on date \| null · required	When it stopped: the cancellation date given, else the last charge. Null while it is running.
first_date date · required
last_amount Money · required
last_date date · required
merchant_key string · required	The charge's stable key: the merchant or payer it groups by. Pass it to `recurring.set_status`.
monthly_cost Money · required	What it comes to per month at its cadence.
name string · required	The name the charge appears under.
next_expected date · required
occurrences integer · required	How many charges were seen.
previous_amount Money · required	The usual amount before the latest charge.
price_changed boolean · required	The latest charge differs from the usual amount.
status string · required	The household's verdict: `detected` (none given), `confirmed`, `dismissed` (not a recurring charge) or `cancelled`.

Example

curl -X POST "https://api.lumaledger.app/v1/recurring/status" \
  -H "Authorization: Bearer $LUMALEDGER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "…",
    "status": "…"
  }'

Objects

BillForecast

The recurring charges and income projected over the coming months.

Fields

biggest array of ForecastOccurrence · required	The largest expected bills, each once, on the day it lands next.
charges array of ForecastCharge · required	Bills first, costliest first, then income.
end date · required
expected_in Money · required
expected_out Money · required
horizon string · required	`quarter` or `year`.
monthly_out Money · required	`expected_out` per month over the horizon.
months array of ForecastMonth · required
net Money · required
start date · required
today date · required

CalendarCharge

The recurring charge a calendar item belongs to.

Fields

cadence string · required
expected_amount Money · required
last_date date · required
merchant_key string · required
occurrences integer · required
status string · required	The household's verdict, as in `recurring.list`.

CalendarItem

Fields

account_id integer \| null · required
account_name string \| null · required
amount Money · required	Always positive; `flow` says which way it moved.
date date · required
flow string · required	`in` or `out`.
name string · required
overdue boolean · required	Expected on a day already gone, and not yet arrived.
projected boolean · required	Expected on this day rather than seen.
recurring CalendarCharge \| null · required	The recurring charge it belongs to. Null for a one-off transaction.
transaction_id integer \| null · required	The transaction behind a seen item (see `transactions.get`). Null when projected.

CalendarTotals

Fields

actual_in Money · required
actual_out Money · required
projected_in Money · required
projected_out Money · required

CancelGuide

Where and how to cancel this merchant, from LumaLedger's curated list.

Fields

id string · required
method string · required	How it is cancelled: `web`, `phone`, `store_apple`, `store_google`, `store_amazon`, `in_person`.
name string · required
phone string \| null · required
steps array of string · required	Step keys, in order. They name steps; they are not sentences.
url string \| null · required

ForecastCharge

Fields

amount Money · required	One occurrence.
cadence string · required
flow string · required	`in` or `out`.
merchant_key string · required
name string · required
next_date date · required
occurrences integer · required	How many times it is expected over the horizon.
status string · required	`detected` or `confirmed`; dismissed and cancelled charges are left out.
total Money · required	`amount` times `occurrences`.

ForecastMonth

Fields

expected_in Money · required
expected_out Money · required
month string · required	`YYYY-MM`.
net Money · required
occurrences array of ForecastOccurrence · required

ForecastOccurrence

Fields

amount Money · required
cadence string · required
date date · required
flow string · required	`in` or `out`.
merchant_key string · required
name string · required

Money

An amount and its currency. `amount` is a base-10 string with two decimal places and an optional leading minus sign. Parse it with a decimal type, not a float.

Fields

amount string · required	Pattern: `^-?\d+\.\d{2}$`.
currency string · required	ISO 4217 code. Pattern: `^[A-Z]{3}$`.

RecurringCalendarOut

Days start to end: what happened and what is expected.

Fields

end date · required
items array of CalendarItem · required	By day; within a day, seen before expected and income first.
start date · required
today date · required	The server's today, which `overdue` and `projected` are read against.
totals CalendarTotals · required

RecurringCharge

A charge or an income that repeats, found by the recurring detector (or declared by the household), with the household's verdict on it.

Fields

activity string · required	What the charges say: `active`, `missed` (late) or `ended`. A cancelled charge is always `ended`.
amount Money · required	The usual amount of one charge. Always positive.
cadence string · required	One of `weekly`, `biweekly`, `four_weekly`, `monthly`, `quarterly`, `yearly`.
cancel_guide CancelGuide \| null · required	How to cancel it, when LumaLedger knows the merchant. Expenses only.
confidence string · required	`high` (seen enough times to be sure) or `likely` (a regular pattern seen fewer times).
declared_cadence boolean · required	The cadence was declared by the household, not measured.
direction string · required	`expense` (a bill, a subscription) or `income` (a paycheck).
ended_on date \| null · required	When it stopped: the cancellation date given, else the last charge. Null while it is running.
first_date date · required
last_amount Money · required
last_date date · required
merchant_key string · required	The charge's stable key: the merchant or payer it groups by. Pass it to `recurring.set_status`.
monthly_cost Money · required	What it comes to per month at its cadence.
name string · required	The name the charge appears under.
next_expected date · required
occurrences integer · required	How many charges were seen.
previous_amount Money · required	The usual amount before the latest charge.
price_changed boolean · required	The latest charge differs from the usual amount.
status string · required	The household's verdict: `detected` (none given), `confirmed`, `dismissed` (not a recurring charge) or `cancelled`.

RecurringChargeList

A page of recurring charges and income, by merchant_key.

Fields

data array of RecurringCharge · required
has_more boolean · required
next_cursor string \| null · required

RecurringDeclaration

Fields

cadence string · required	One of `weekly`, `biweekly`, `four_weekly`, `monthly`, `quarterly`, `yearly`. Pattern: `^(weekly\|biweekly\|four_weekly\|monthly\|quarterly\|yearly)$`.
merchant string · required	Who is paid (or pays), as a transaction's description names them, or a `merchant_key`. A unique part of the name is enough.

RecurringStatusUpdate

Fields

ended_on date \| null	With `cancelled`: the day it ended. Defaults to today.
merchant_key string · required	The charge, from `recurring.list`.
status string · required	`confirmed`, `dismissed` (not a recurring charge), `cancelled`, or `detected` to forget the verdict. Pattern: `^(confirmed\|dismissed\|cancelled\|detected)$`.