Skip to content


This document describes services running as part of the Banks application.


You can manually create an app token and launch the built service.

# Watch services
$ yarn watch:services:prod
# In another terminal
$ export COZY_URL=''
$ export COZY_CREDENTIALS=$(cozy-stack instances token-app banks)
$ node build/budgetAlerts.js

Some services like the “budgetAlerts” one expose a CLI that can perform service related tasks.

yarn run services:budgetAlerts --help



slug: categorization

This service role is to categorize transactions. It is bound to no event at all, so it’s not automatically triggered and needs to be explicitly called by a konnector or another service. This service is called from konnectors so that transactions are categorized as soon as possible (no debounce involved).

When this service is ran, it gets all that has the toCategorize property with a true value. Then it slices it into chunks and categorizes the most chunks it can before the service is stopped by the stack. If there are some uncategorized transactions remaining, it restarts itself to finish the work. If all transactions have been categorized, it calls the onOperationOrBillCreate service to trigger all other features.

See the categorization documentation for more details about the categorization implementation.


slug: onOperationOrBillCreate

This service has many roles. It does:

  • Bills matching
  • Notifications (push & email)
  • Apps suggestions

It is bound to the io.cozy.bills creation only. The creation of should be managed by calling the categorization service. See the next section for more precise informations about that.

Account stats

slug: stats

Computes statistics on bank accounts and save the results in doctype.

Automatic groups

slug: autogroups

Whenever an is created, we check if it could belong in an automatic group based on its type (checkings, savings, credit cards). These documents are created with the auto: true attributes.

Budget alerts

slug: budgetAlerts

A user can configure alerts to be alerted whenever the sum of its expenses has gone past a maximum threshold per month. The notification is sent as part of the onOperationOrBillCreate service.

It is configured from a document and the last notification date and amount are saved.

A debug service is built to be able to only run this particular part and not the whole onOperationOrBillCreate service. It is possible to run it from the Debug tab in the application (or via Bender).


slug: recurrence

Tries to find recurrence groups when new operations are inserted in the Cozy. It either creates new recurrence groups or attaches transactions to existing recurrence groups.

See Paper “Paiements recurrents” for more information on the service.

Konnector alerts

slug: konnectorAlerts

It monitors the jobs and sends a notification when a konnector has failed. Here are the rules for those notifications:

  • They should only be sent for LOGIN_FAILED and USER_ACTION_NEEDED errors
  • They should only be sent for automatic jobs (not manual)
  • We should not send a notification if the state stays the same

I am writing a banking konnector, what should I do?

If you want to benefit from all the features of these services, the most straightforward is to add toCategorize: true to the your konnector creates, save these documents and then call the categorization service.

Here is an example:

const { cozyClient, BaseKonnector } = require('cozy-konnector-libs')

class MyKonnector extends BaseKonnector {
  async saveTransactions() {
    const transactions = await this.fetchTransactions()
    transactions.forEach(t => (t.toCategorize = true))

    // save `transactions`

    await'service', {
      name: 'categorization',
      slug: 'banks'

Finally, you will need a permission to create document. Add the following permission to your manifest.konnector:

  "permissions": {
    "jobs": {
      "description": "Required to run applications services",
      "type": ""

With this, the transactions you created will be categorized, then the onOperationOrBillCreate service will be launched and do its work.