Skip to content

Browse the Service Catalog

The Service Catalog is a dedicated matching tool at /subscriptions/catalog that helps users tune how BillTracker recognizes recurring charges from their bank transactions. It is intentionally separate from the Subscriptions page, which focuses on tracked subscriptions and bank-backed recommendations.

This page explains what the catalog is, how the matching engine scores transactions against it, and how to add custom bank descriptors that improve matching for your specific account.

What does the page do?

The page surfaces the catalog in three sections:

  • Tracking — catalog entries that already have a bill linked. Each row shows price-drift indicators and exposes an Edit action in BillModal. A Re-link button opens a searchable dialog to swap or remove the catalog link.
  • Custom bank descriptors — per-user payee strings that augment the catalog for the current user only. Adding an exact bank-statement string dramatically improves auto-matching for that user's account.
  • All catalog entries — searchable and filterable list of every known service. Untracked entries can still be tracked individually or in bulk.

A compact Improve Matching card on the Subscriptions page links to the Service Catalog whenever the user needs to tune descriptors, fix a wrong service link, or connect an existing bill to a known service.

How does the matching engine score a transaction?

lookupCatalog scores a transaction against the catalog in this order:

  1. Bank descriptors — score 2000+. Includes researched descriptors (NETFLIX *SUBSCRIPTION, AMZN PRIME VIDEO) and the user's custom descriptors. This resolves cases where the bank payee string bears no obvious similarity to the service name.
  2. Name / domain fuzzy match — score 1000 / 500. Used as a fallback when no bank descriptor matches.

catalogMatchPayload includes starting_monthly_usd so the recommendation engine can sanity-check amounts against the catalog starting price.

How do I add a custom bank descriptor?

Per-user custom descriptors are merged into loadCatalog at load time, so they improve auto-matching for the current user's account without affecting any other user. The Manage Descriptors dialog lets a user:

  • Add an exact payee string from a bank statement
  • Delete a custom descriptor
  • See which catalog entry a custom descriptor is attached to

How do I re-link a tracked service to a different catalog entry?

A tracked catalog entry has a one-to-one link to a bill via bills.catalog_id. The Re-link dialog lets a user:

  • Swap the link to a different catalog entry (e.g., correcting "Amazon Prime" to a different known subscription)
  • Remove the link entirely (turning the bill into a regular non-catalog bill)
  • Search the catalog by name, alias, or category

What happens when the catalog fails to load?

Catalog load failures surface both inline (in the section that failed) and as toast feedback. The page is fully keyboard-navigable and works on mobile.

Which API endpoints back this page?

Method Path Purpose
GET /api/subscriptions/catalog List catalog entries with merged user descriptors
POST /api/subscriptions/catalog/:id/descriptors Add a custom bank descriptor
DELETE /api/subscriptions/catalog/:id/descriptors/:descriptor Remove a custom bank descriptor
PATCH /api/bills/:id/catalog-link Set or clear the catalog id on a bill

See also

Next steps