Subscriptions

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

Subscription`subscription`

A recurring subscription with price, cadence, and renewal.

subscriptions_findFindthrough vritto_find

Read Subscriptions: one plan by id, or plans filtered by renewal dates, status, text, category, cadence or card. With no filter it returns status counts, monthlyTotalUsd and capped lean rows. Use for renewal, spend and card questions, and to resolve ids before any write.

Field	Type	Description
id	string	Return just this subscription.
status	one of active, trial, paused, cancelled, watchlist	Only plans in this status.
from	string	Next renewal on or after this date. ALWAYS pass from/to when the question concerns a period.
to	string	Next renewal on or before this date.
query	string	Text to match: merchant, plan or website.
category	one of streaming, software, productivity, news, learning, cloud, finance, fitness, shopping, gaming, household, other
cadence	one of weekly, monthly, quarterly, yearly, one_time, unknown
card	string	The paying card: its last four digits or a Finance card id.
limit	integer	Rows to return, default 25.
detail	one of summary, full	"summary" (default) counts, monthlyTotalUsd and lean rows; "full" every field incl. notes, payment card, trial and tags.

Example input

{}

subscriptions_addCreate or Updatethrough vritto_create or vritto_update

Add one subscription (merchantName required). A merchant already on file is updated instead of duplicated. The server resolves the logo and derives nextBillingOn from lastChargeOn and cadence when omitted. Example: record { merchantName 'Netflix', price 22.99, cadence 'monthly', category 'streaming', nextBillingOn '2026-07-12' }.

Field	Type	Description
record*	object	Subscription fields; merchantName is required.
record.id	string	Leave out when adding; to change a subscription use subscriptions_change.
record.merchantName	string	Merchant or service name, e.g. 'Netflix'. Required when creating.
record.source	one of manual, gmail, outlook, logo_dev, import, bank	Where the record came from. Set by the ingestion pipeline; leave unset.
record.websiteDomain	string	Merchant website domain, e.g. 'netflix.com'. Also used to resolve the logo.
record.category	one of streaming, software, productivity, news, learning, cloud, finance, fitness, shopping, gaming, household, other	Spending category (default 'other').
record.status	one of active, trial, paused, cancelled, watchlist	Lifecycle status (default 'active'). Use 'trial' for trials, 'watchlist' for services under consideration, 'cancelled' to record a cancellation while keeping history.
record.cadence	one of weekly, monthly, quarterly, yearly, one_time, unknown	Billing cycle (default 'monthly').
record.currency	string	ISO 4217 currency code as the source states it, e.g. 'INR'; omit when none is stated (the account's currency is used).
record.price	number	Price per billing cycle in the given currency (default 0).
record.startedOn	string	Date the subscription started (YYYY-MM-DD).
record.trialEndsOn	string	Trial end date (YYYY-MM-DD).
record.nextBillingOn	string	Next renewal/billing date (YYYY-MM-DD). If omitted, derived from lastChargeOn and cadence.
record.lastChargeOn	string	Most recent charge date (YYYY-MM-DD).
record.cancellationDate	string	Planned or actual cancellation date (YYYY-MM-DD).
record.cancellationUrl	string	The page where this subscription is actually cancelled, e.g. 'https://www.netflix.com/cancelplan'. Set it when the user gives one or a receipt names one; never guess a URL.
record.paymentMethod	one of card, bank, paypal, app_store, google_play, other, unknown	How the subscription is paid (default 'unknown').
record.cardId	string	Finance card id that pays for this, from finance_queryOverview. Never a card number, and never invented.
record.cardNetwork	string	Card network for card payments, e.g. 'Visa' or 'Chase'.
record.cardLast4	string	Last four digits of the paying card. Never store full card numbers.
record.ownerEmail	string	Email address of the account that owns the subscription.
record.planName	string	Plan or tier name, e.g. 'Premium 4K'.
record.seats	integer	Number of seats or licenses (default 1).
record.renewalReminderDays	integer	Days before renewal to remind (default 7).
record.autopay	boolean	Whether it renews automatically (default true).
record.notes	string	Notes, e.g. cancellation instructions.
record.ownerPersonId	string	People person id when the subscription is really a family member's; omit for the account owner.
record.tags	list of string	Tags.

Example input

{
  "record": {
    "merchantName": "Spotify",
    "category": "streaming",
    "status": "active",
    "cadence": "monthly",
    "price": 11.99,
    "currency": "USD",
    "nextBillingOn": "2026-10-12"
  }
}

subscriptions_changeUpdatethrough vritto_update

Change one subscription by record.id; sent fields merge. Cancel with status 'cancelled' and a cancellationDate (the record stays), pause, restart with status 'active' and startedOn, or change price, plan or card. Resolve the id with subscriptions_find first.

Note: To record a cancellation and keep the history, set status 'cancelled' and a cancellationDate.

Field	Type	Description
record*	object	The subscription's id plus the fields to change.
record.id*	string	Subscription ID from a prior subscriptions_find result, never invented.
record.merchantName	string	Merchant or service name, e.g. 'Netflix'. Required when creating.
record.websiteDomain	string	Merchant website domain, e.g. 'netflix.com'. Also used to resolve the logo.
record.category	one of streaming, software, productivity, news, learning, cloud, finance, fitness, shopping, gaming, household, other	Spending category (default 'other').
record.status	one of active, trial, paused, cancelled, watchlist	Lifecycle status (default 'active'). Use 'trial' for trials, 'watchlist' for services under consideration, 'cancelled' to record a cancellation while keeping history.
record.cadence	one of weekly, monthly, quarterly, yearly, one_time, unknown	Billing cycle (default 'monthly').
record.currency	string	ISO 4217 currency code as the source states it, e.g. 'INR'; omit when none is stated (the account's currency is used).
record.price	number	Price per billing cycle in the given currency (default 0).
record.startedOn	string	Date the subscription started (YYYY-MM-DD).
record.trialEndsOn	string	Trial end date (YYYY-MM-DD).
record.nextBillingOn	string	Next renewal/billing date (YYYY-MM-DD). If omitted, derived from lastChargeOn and cadence.
record.lastChargeOn	string	Most recent charge date (YYYY-MM-DD).
record.cancellationDate	string	Planned or actual cancellation date (YYYY-MM-DD).
record.cancellationUrl	string	The page where this subscription is actually cancelled, e.g. 'https://www.netflix.com/cancelplan'. Set it when the user gives one or a receipt names one; never guess a URL.
record.paymentMethod	one of card, bank, paypal, app_store, google_play, other, unknown	How the subscription is paid (default 'unknown').
record.cardId	string	Finance card id that pays for this, from finance_queryOverview. Never a card number, and never invented.
record.cardNetwork	string	Card network for card payments, e.g. 'Visa' or 'Chase'.
record.cardLast4	string	Last four digits of the paying card. Never store full card numbers.
record.ownerEmail	string	Email address of the account that owns the subscription.
record.planName	string	Plan or tier name, e.g. 'Premium 4K'.
record.seats	integer	Number of seats or licenses (default 1).
record.renewalReminderDays	integer	Days before renewal to remind (default 7).
record.autopay	boolean	Whether it renews automatically (default true).
record.notes	string	Notes, e.g. cancellation instructions.
record.ownerPersonId	string	People person id when the subscription is really a family member's; omit for the account owner.
record.tags	list of string	Tags.

Example input

{
  "record": {
    "id": "sub_spotify",
    "status": "cancelled",
    "cancellationDate": "2026-10-23"
  }
}

subscriptions_removeDeletethrough vritto_delete

Remove (archive and mark cancelled) one subscription. Only for explicit removal requests; to record a cancellation while keeping the record, use subscriptions_change with status 'cancelled'. Resolve the id with subscriptions_find first.

Field	Type	Description
id	string	The subscription to remove.
subscriptionId	string	Older name for id.

Subscriptions

Subscriptionsubscription

Subscription`subscription`