> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getlago.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration to v1.52.0

Dear Lago Community, 👋

We're writing to inform you about important changes in Lago v1.52.0 that introduce **multi-billing-entity billing on a single customer** and a **faster invoice search**.

# What are the changes?

## Billing entity on wallet transactions

With multi-billing-entity billing, a customer's subscriptions, wallets and invoices are no longer tied to a single [billing entity](/guide/billing-entities), and different wallets of the same customer can belong to different entities.

To keep accounting traceable, **wallet transactions now store their own `billing_entity_id`**, stamped at creation time. A transaction therefore always reports the entity it was actually created under, even if the wallet is later moved to another entity. Only transactions created after the move carry the new entity.

As a result, **existing wallet transactions must be backfilled** with the billing entity of their customer. This is done through a rake task that must be **triggered manually**.

## Search terms on invoices

Invoices now carry a denormalized **`search_terms` column**, backed by a GIN trigram index. It concatenates the invoice number, the purchase order number and the customer identifiers the invoice list searches on: name, first name, last name, legal name, external ID and email.

Invoices created, finalized or regenerated from now on maintain their search terms automatically, and so do the invoices of a customer whose details change. However, **existing invoices must be backfilled**. This is done through a rake task that must be **triggered manually**.

# Why are we doing this?

Previously, the billing entity of a wallet transaction could only be inferred from its customer, which had exactly one entity. Now that a wallet can be moved between entities, inferring the entity would retroactively rewrite the history of past transactions. Storing the entity on each transaction keeps historical records accurate and entity-level accounting reliable.

Searching the invoice list previously had to join and scan the `customers` table on every keystroke, which gets slower as the invoice table grows. Reading the terms from a single indexed column on `invoices` keeps the search fast whatever the volume.

# What should self-hosted users do?

<Note>
  Cloud users do not need to follow these instructions as the migration will be performed by the Lago Team.
</Note>

<Warning>
  If you're using a version below `v1.50.0`, please first follow the migration steps for [v1.50.0](/guide/migration/migration-to-v1.50.0).
  Only after completing those should you proceed to v1.52.0.
</Warning>

## Migration Steps

### 1. Install Lago v1.52.0

Install the new version. Schema migrations (new tables and columns) will run automatically on startup.

### 2. Backfill wallet transactions

Open a shell on your API server and run the migration task:

```bash theme={"dark"}
bundle exec rails migrations:backfill_wallet_transactions_billing_entity
```

The backfill runs in a background job. The task reports the number of remaining wallet transactions until it completes.

<Note>
  The backfill task is safe to run multiple times. It only targets wallet transactions without a billing entity, so already-migrated records are left untouched.
</Note>

### 3. Backfill invoice search terms

From the same shell, run the second migration task:

```bash theme={"dark"}
bundle exec rails migrations:backfill_invoices_search_terms
```

Unlike the previous task, this one returns as soon as the job is enqueued. The backfill then walks the invoices in the background, on the `low_priority` queue, so make sure a Sidekiq worker is draining that queue. The job logs `Finished backfilling invoices.search_terms` once the walk is over.

<Note>
  If the backfill is interrupted, resume it from the last invoice ID it reported instead of starting over:

  ```bash theme={"dark"}
  START_AFTER=<invoice id> bundle exec rails migrations:backfill_invoices_search_terms
  ```
</Note>

<Note>
  This task is also safe to run multiple times. It only rewrites the invoices whose search terms have changed, so already-migrated records are left untouched.
</Note>

# Get Involved

If you have any questions or encounter issues during the migration, please reach out to us via the Slack community. Our team is here to help you through this transition.

Thanks for your understanding and continued support.

The Lago Team