Monzo

Monzo is a digital bank. The Monzo integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] connects your Monzo accounts to Home Assistant. You can monitor account and pot balances, track how much you have spent today, react to new transactions, and move money between an account and its pots.

Prerequisites and approval

1. Sign in to the Monzo developer portal with your Monzo account.

2. Go to Clients > New OAuth Client to create an OAuth client for Home Assistant.

3. Enter the following values. Use the redirect URL exactly as shown; do not replace it with the URL of your Home Assistant instance:

   • Name: Home Assistant
   • Logo URL: Leave this field blank
   • Redirect URLs: https://my.home-assistant.io/redirect/oauth
   • Description: For example, Used by the Monzo Home Assistant integration
   • Confidentiality: Confidential

4. Once submitted, you can proceed with adding the integration.

   • Go to Settings > Devices & services and add the Monzo integration.
   • Enter the client ID and client secret for the OAuth client you created in the Monzo developer portal.
   • After you authorize Home Assistant access, approve the request in the Monzo app. Home Assistant waits for this second approval and completes setup automatically. If you see Approval timed out or Connection error, follow the on-screen instructions to try again.

Configuration

To add the Monzo service to your Home Assistant instance, use this My button:

Adding a second account

1. Create another OAuth client by repeating the steps above.
2. In Home Assistant, add the new credentials before adding the new integration entry.
   • On the Devices & services page, select the three dots menu in the top-right corner, select Application credentials, and then select Add application credentials.
3. Return to Devices & services > Monzo, select Add entry, and authenticate the second account.

Supported functionality

The integration creates a device for each Monzo account and pot.

Sensors

Account and pot devices provide the following sensor:

• Balance: The current balance of the account or pot.

Account devices also provide the following sensors:

• Total balance: The current balance of that account plus all of its pots.
• Spent today: The amount spent from the account since around 4:00 AM (Monzo’s day boundary), shown as a positive value. Money received does not reduce this amount.

Transaction events

The integration creates a Transaction eventEvery time something happens in Home Assistant, an event is fired. Different types of events are fired when, for example, an entity’s state changes, an action such as light.turn_on is performed, or Home Assistant starts. All entities produce state change events. Every time the state or the attributes of an entity change, a state change event is produced. Events can be used to trigger automations. For example, you can trigger an automation to turn on a speaker in a room when a light in that room turns on. [Learn more] entityAn entity represents a sensor, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a device or a service. [Learn more] for each Monzo account. When Monzo reports a new transaction, the entity fires a transaction_created event and the integration refreshes the account and pot balances.

The complete transaction data provided by Monzo is available in the event entity’s data attribute for use in automations. By default, Home Assistant also stores this data in the recorder history.

Transaction events require either Home Assistant Cloud or an external URL configured under Settings > System > Network that is accessible from the web.

List of actions

The Monzo integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following actions. Each link below opens a dedicated page with examples, parameters, and a step-by-step UI walkthrough.

• Deposit into pot (monzo.deposit_into_pot) Moves money from a Monzo account into a pot.

• Withdraw from pot (monzo.withdraw_from_pot) Moves money from a Monzo pot into an account.

For an overview of every action across all integrations, see the actions reference.

Monzo automation examples

These blueprints provide reusable automations for moving money between a Monzo account and one of its pots.

Automation: keep an account at a target balance

This blueprint keeps a selected account at a target balance. When the account balance changes, it deposits any excess into the selected pot or withdraws the shortfall from it. The withdrawal is limited to the pot’s available balance. The automation also checks the balance every 15 minutes as a fallback.

For example, you can keep 1,000 in your account’s currency in your current account and move the remainder to or from a savings pot.

Prefer to configure this automation manually? Use the YAML below.

alias: Keep a Monzo account at a target balance
variables:
  account_device_input: YOUR_ACCOUNT
  pot_device_input: YOUR_POT
  account_balance_entity: YOUR_ACCOUNT_BALANCE
  pot_balance_entity: YOUR_POT_BALANCE
  target_balance_input: 1000

triggers:
  - trigger: state
    entity_id: YOUR_ACCOUNT_BALANCE
  - trigger: time_pattern
    minutes: "/15"

conditions:
  - condition: template
    value_template: >
      {{
        is_number(states(account_balance_entity))
        and is_number(states(pot_balance_entity))
        and device_id(account_balance_entity) == account_device_input
        and device_id(pot_balance_entity) == pot_device_input
      }}

actions:
  - variables:
      account_balance_value: >
        {{ states(account_balance_entity) | float }}
      pot_balance_value: >
        {{ states(pot_balance_entity) | float }}
      target_balance_value: >
        {{ target_balance_input | float }}
  - choose:
      - conditions:
          - condition: template
            value_template: >
              {{ account_balance_value > target_balance_value }}
        sequence:
          - action: monzo.deposit_into_pot
            data:
              account: YOUR_ACCOUNT
              pot: YOUR_POT
              amount: >
                {{
                  (account_balance_value - target_balance_value) | round(2)
                }}
      - conditions:
          - condition: template
            value_template: >
              {{
                account_balance_value < target_balance_value
                and pot_balance_value > 0
              }}
        sequence:
          - action: monzo.withdraw_from_pot
            data:
              account: YOUR_ACCOUNT
              pot: YOUR_POT
              amount: >
                {{
                  [
                    target_balance_value - account_balance_value,
                    pot_balance_value,
                  ]
                  | min
                  | round(2)
                }}

mode: single
max_exceeded: silent

Automation: reimburse purchases from a pot by merchant

This blueprint watches the selected account’s Transaction event entity. When it receives a debit transaction from the specified merchant, it withdraws the transaction amount from a selected pot. For example, after a Netflix payment, it can move the same amount from a subscriptions pot back into the account.

Before importing the blueprint, create an Input text helperA helper is a virtual entity you create inside Home Assistant. It is not backed by a physical device. Helpers store values, track state, or do calculations that your automations and dashboards need. [Learn more] under Settings > Devices & services > Helpers. Set its maximum length to 255 characters. The blueprint uses it to remember recent transaction IDs and guard against a repeated webhook moving money twice.

Prefer to configure this automation manually? Use the YAML below.

alias: Reimburse Monzo purchases from a pot by merchant
variables:
  account_device_input: YOUR_ACCOUNT
  transaction_event_entity: YOUR_TRANSACTION_EVENT
  merchant_name_input: YOUR_MERCHANT_NAME
  processed_transaction_entity: YOUR_PROCESSED_TRANSACTION

triggers:
  - trigger: event.received
    target:
      entity_id: YOUR_TRANSACTION_EVENT
    options:
      event_type:
        - transaction_created

actions:
  - variables:
      transaction: >
        {{ trigger.to_state.attributes.get('data', {}) }}
  - variables:
      transaction_amount: >
        {{ transaction.get('amount', 0) | int }}
      transaction_id: >
        {{ transaction.get('id', '') }}
      transaction_merchant_name: >
        {% set merchant = transaction.get('merchant') %}
        {{ merchant.get('name', '') if merchant is mapping else '' }}
      processed_transaction_ids: >
        {% set value = states(processed_transaction_entity) %}
        {{
          value.split('|')
          if value not in ['unknown', 'unavailable', '']
          else []
        }}
  - condition: template
    value_template: >
      {{
        transaction_id
        and transaction_id not in processed_transaction_ids
        and device_id(transaction_event_entity) == account_device_input
        and transaction_amount < 0
        and not transaction.get('decline_reason')
        and (transaction_merchant_name | lower)
          == (merchant_name_input | lower)
      }}
  - action: monzo.withdraw_from_pot
    data:
      account: YOUR_ACCOUNT
      pot: YOUR_POT
      amount: >
        {{ (transaction_amount | abs / 100) | round(2) }}
  - action: input_text.set_value
    target:
      entity_id: YOUR_PROCESSED_TRANSACTION
    data:
      value: >
        {{ ([transaction_id] + processed_transaction_ids)[:5] | join('|') }}

mode: queued
max_exceeded: silent

Data updates

The integration pollsData polling is the process of querying a device or service at regular intervals to check for updates or retrieve data. By defining a custom polling interval, you can control how frequently your system checks for new data, which can help optimize performance and reduce unnecessary network traffic. [Learn more] Monzo for account and pot data every minute. When Monzo sends a new transaction through a webhook, the integration fires the account’s Transaction event entity and requests an immediate refresh of the account and pot balances.

New accounts and pots are added after a successful refresh. Devices for accounts and pots that Monzo no longer returns are removed.

If Home Assistant cannot register a webhook, account and pot sensors continue to update every minute, but the Transaction event entities do not receive new events.

Known limitations

• Transaction events require either Home Assistant Cloud or an external URL configured under Settings > System > Network that is accessible from the web.
• Pot transfers only work between a pot and its associated account in the same Monzo connection.
• Loan, Flex, and Rewards accounts do not support pot transfers.
• You cannot withdraw from a pot that has Added security enabled. Use the Monzo app to withdraw from that pot.

Troubleshooting

Monzo displays a network error during authentication

Symptom: “Network error” after entering your email address

During setup or reauthentication, the Monzo authentication page displays Network error after you enter your email address.

Description

This error can occur when the redirect URL configured for your OAuth client in the Monzo developer portal is incorrect.

Resolution

In the Monzo developer portal, open the OAuth client used by Home Assistant and set Redirect URLs to https://my.home-assistant.io/redirect/oauth. Use this URL exactly as shown. Do not replace it with a local or Home Assistant Cloud URL. Then, retry authentication in Home Assistant.

Approval times out

Symptom: “Approval timed out”

Home Assistant displays Approval timed out while you are setting up or reauthenticating the integration.

Description

After you authorize Home Assistant in your browser, Monzo requires a second approval in the Monzo app. Home Assistant waits up to five minutes for this approval.

Resolution

Approve the request in the Monzo app, then select Try again in Home Assistant.

Transaction events are not received

Symptom: balances update, but no transaction events are received

Account and pot balances continue to update, but the Transaction event entity does not receive transaction_created events.

Description

Monzo must be able to reach the Home Assistant webhook from the web. Balance sensors use polling and can continue to work when the webhook is unavailable.

Resolution

Use Home Assistant Cloud or configure a publicly accessible external URL under Settings > System > Network. Home Assistant automatically retries webhook registration after temporary failures.

A pot transfer fails

Symptom: an action reports that the transfer failed or was rejected

The Deposit into pot or Withdraw from pot action does not complete successfully.

Resolution

• Make sure the account and pot belong to the same Monzo connection and that the pot belongs to the selected account.
• Do not select a Loan, Flex, or Rewards account.
• For withdrawals, make sure the pot has enough money and does not have Added security enabled.
• If Home Assistant cannot confirm whether a transfer completed, check the balance in the Monzo app before trying again.

If the problem continues, download diagnostics from the Monzo integration entry and include them when reporting the issue.

Removing the integration

This integration follows the standard integration removal process. Home Assistant also attempts to remove the webhooks it registered with Monzo. No extra steps are required.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.