Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/soker90/finper/llms.txt

Use this file to discover all available pages before exploring further.

The Subscriptions module helps you stay on top of every recurring charge — streaming services, cloud tools, gym memberships, and anything else that hits your account on a regular cycle. You create a subscription once with its billing cycle and linked account/category, then Finper automatically calculates the next expected payment date from your real transaction history. A built-in detection engine watches every new transaction you record and surfaces likely subscription matches for you to confirm or dismiss in one click.

​
Data Model

​
Subscription Fields

FieldTypeRequiredDescription
namestring✅Service name, e.g. "Netflix"
amountnumber✅Expected charge amount per cycle
currencystring❌ISO 4217 currency code (e.g. "EUR", "USD")
cyclenumber✅Billing frequency in months — an integer from 1 to 60 (e.g. 1 = monthly, 3 = quarterly, 12 = annually)
nextPaymentDatenumber | nullcalculatedUnix timestamp (ms) of the next expected payment; null when no transactions are linked yet — never set manually
categoryIdObjectId✅Expense category for matching transactions
accountIdObjectId✅Account that receives the charge
logoUrlstring❌URL of the service’s logo image
cycle is a number, not a named string. Pass the billing interval in months: 1 for monthly, 2 for bimonthly, 3 for quarterly, 6 for semi-annually, 12 for annually, or any integer from 1 to 60 for custom intervals.

​
SubscriptionCandidate Fields

A SubscriptionCandidate is a temporary record created automatically when Finper detects that a new transaction might be a subscription payment. It sits in a pending queue until you confirm or discard it.
FieldTypeDescription
transactionIdObjectIdThe transaction detected as a possible payment
subscriptionIdsObjectId[]One or more subscriptions whose nextPaymentDate matches the transaction date
createdAtDateAuto-set creation timestamp (newest first in listing)

​
Endpoints

MethodPathDescription
POST/api/subscriptionsCreate a subscription
GET/api/subscriptionsList all subscriptions, ordered by nextPaymentDate ascending
PUT/api/subscriptions/:idEdit a subscription
DELETE/api/subscriptions/:idDelete a subscription
GET/api/subscriptions/:id/transactionsList transactions already linked to this subscription
GET/api/subscriptions/:id/matching-transactionsList unlinked transactions that could belong to this subscription (max 50)
POST/api/subscriptions/:id/link-transactionsLink a batch of transactions to the subscription
DELETE/api/subscriptions/:id/unlink-transactions/:transactionIdRemove the link between a transaction and this subscription
GET/api/subscriptions/candidatesList pending candidates awaiting your confirmation
POST/api/subscriptions/candidates/:id/assignConfirm a candidate — links the transaction to the chosen subscription
POST/api/subscriptions/candidates/:id/dismissDiscard a candidate without linking anything

​
Next Payment Date Calculation

nextPaymentDate is always computed — Finper never stores a date you supply manually. The calculation rule is straightforward: 
lastTx = most recent transaction linked to this subscription (by date)

nextPaymentDate = lastTx
  ? lastTx.date + (cycle × one month in ms)
  : null
advanceDate advances a timestamp by exactly cycle months using JavaScript’s native Date.setMonth(), so edge cases (e.g. month-end overflow) follow JavaScript’s built-in date arithmetic. This recalculation runs automatically after every link or unlink operation, so nextPaymentDate is always consistent with the latest payment you have recorded.
Until at least one transaction is linked, nextPaymentDate is null. The subscription still appears in the list — it is sorted after all entries with a concrete date.

​
Automatic Candidate Detection

When you create any transaction, Finper runs a background check to see if it could be a subscription payment. This check is fire-and-forget — it runs asynchronously and never delays or fails the transaction creation call.
1

Transaction is saved

Your POST /api/transactions call completes normally and returns the new transaction.
2

±7-day window check

Finper searches for subscriptions that belong to the same user, use the same accountId and categoryId as the new transaction, and whose nextPaymentDate falls within ±7 days of the transaction’s date.
3

Candidate record created

If one or more matching subscriptions are found, a single SubscriptionCandidate is created linking the transaction to all matching subscriptions. If no matches are found, nothing is created.
4

Review in the candidates queue

Call GET /api/subscriptions/candidates to see all pending suggestions. Each candidate shows the transaction details alongside the possible subscription matches.
5

Confirm or dismiss

Use POST /api/subscriptions/candidates/:id/assign with the chosen subscriptionId to confirm the link, or POST /api/subscriptions/candidates/:id/dismiss to discard the suggestion. Both actions delete the candidate record.
The ±7-day window intentionally tolerates real-world billing variance — charges that arrive a few days early or late are still detected as likely matches.

​
Linking Transactions Manually

If Finper’s auto-detection hasn’t surfaced a particular transaction as a candidate (perhaps the subscription was created after the transactions were recorded), you can link them manually:
1

Discover matching transactions

GET /api/subscriptions/:id/matching-transactions returns up to 50 unlinked transactions that share the subscription’s categoryId and accountId, sorted newest first.
curl -s "http://localhost:3008/api/subscriptions/64a1f2e3b4c5d6e7f8a9b0c5/matching-transactions" \
  -H 'token: <your-jwt>'
2

Link selected transactions

Pass an array of transaction IDs to POST /api/subscriptions/:id/link-transactions. Finper sets subscriptionId on each transaction and recalculates nextPaymentDate.
curl -s -X POST \
  "http://localhost:3008/api/subscriptions/64a1f2e3b4c5d6e7f8a9b0c5/link-transactions" \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "transactionIds": [
      "64b2a3f4c5d6e7f8a9b0c101",
      "64b2a3f4c5d6e7f8a9b0c102",
      "64b2a3f4c5d6e7f8a9b0c103"
    ]
  }'

​
Common Cycle Values

The cycle field accepts any integer from 1 to 60. Common values:
cycle valueBilling Frequency
1Monthly
2Every 2 months
3Quarterly
6Semi-annually
12Annually

​
Examples

​
Creating a Subscription

curl -s -X POST http://localhost:3008/api/subscriptions \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Netflix",
    "amount": 15.99,
    "currency": "EUR",
    "cycle": 1,
    "categoryId": "64a1f2e3b4c5d6e7f8a9b0c3",
    "accountId":  "64a1f2e3b4c5d6e7f8a9b0c1",
    "logoUrl": "https://example.com/logos/netflix.png"
  }'
The response will include nextPaymentDate: null because no transactions are linked yet.

​
Listing and Assigning Candidates

# 1. Fetch pending candidates
curl -s http://localhost:3008/api/subscriptions/candidates \
  -H 'token: <your-jwt>'

# 2. Confirm a candidate — supply the subscriptionId you want to link
curl -s -X POST \
  "http://localhost:3008/api/subscriptions/candidates/64c3b4a5d6e7f8a9b0c20001/assign" \
  -H 'token: <your-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "subscriptionId": "64a1f2e3b4c5d6e7f8a9b0c5" }'

# 3. Discard a candidate you don't want to confirm
curl -s -X POST \
  "http://localhost:3008/api/subscriptions/candidates/64c3b4a5d6e7f8a9b0c20002/dismiss" \
  -H 'token: <your-jwt>'
After confirming, nextPaymentDate on the linked subscription is recalculated automatically and the candidate record is removed from the queue.

Build docs developers (and LLMs) love

Get started for freeTalk to us