A slow Medusa v2 cart or checkout is rarely one bug, so measure before you change anything. The causes with a public record are: the app and the database sitting far apart, timings taken in development mode, a line-item lookup that grew with cart size until v2.19.0 fixed it, and storefront requests that ask for far more data than the page shows. This guide shows how to tell which one you have and what fixes each.
Most "Medusa is slow" reports come down to where the time goes, not to Medusa itself. The first job is to find the one request that is slow, and then the one query or step inside it. I lead commerce and ERP implementations at MithTech, a team of Frappe specialists in Bengaluru that also builds on Medusa.
Measure first
Take timings from a production build (medusa build, then start the built server), with the same database you will run live. For each step of the cart flow, write down the request duration: create cart, add line item, update the cart, complete. Medusa's request log prints the duration of each call, which is how the numbers in #10751 were reported.
One slow request narrows the search. If every request is slow, even the simple ones, look at the infrastructure first. If only add-to-cart and complete are slow, and they grow with the cart, look at the cart workflows and their queries.
Where the app and the database sit
Each cart request makes many database queries, and each pays the network round trip. In #10751 the reporters were on Medusa 2.1.2 with the server in one place and the database in another (a local server with a database in another region, or app and database hosts in different US regions). The maintainers asked where each ran; those who moved them into the same region reported the delay gone.
Put the Medusa server, the worker and PostgreSQL in one region, on one private network where your host offers it. Our Coolify and Hetzner guide runs them on one server.
Large carts: the line-item lookup fixed in v2.19.0
Issue #16232 found that prepareVariantsAndItemsWithPricesStep matched each line item to its variant with .find(), so the work grew with items × variants. That step runs on cart refresh, add-to-cart, cart creation and order creation. The reporter's benchmark (median of 7 runs, one variant per line) put it at about 7 ms per pass for a 1,000-line cart and 27.6 ms for 2,000 lines, against well under a millisecond with a map. For a normal cart of 5 to 20 lines it was microseconds.
So this matters for bulk and B2B orders, imported carts and quote-style flows, not for a typical retail basket. The fix, PR #16233, was merged on 4 August 2026 and is in v2.19.0 and later.
What about database indexes?
The v2 Pricing Module stores prices in price, grouped by price_set, with conditions in price_rule and lists in price_list; variants reach their price set through a module link. The models already declare indexes on the obvious lookup columns, such as price.price_set_id, price.price_list_id, price.currency_code, and price_rule on price_id and attribute. Check what your version has with \d price in psql before you add anything.
Add an index only when EXPLAIN ANALYZE on a real slow query shows a sequential scan on a large table. Build it with CREATE INDEX CONCURRENTLY from psql, so writes to the table keep working; it cannot run inside a transaction block, so it does not belong in a migration that wraps its statements in one.
Smaller responses: fields and limit
A product page that loads every variant, every price and every relation is slow however good the indexes are. Store API list routes accept fields, limit and offset: ask for the fields the page renders, and page through variants instead of loading them all. The smaller payload also helps the browser.
Caching
Medusa v2.11 added a Caching Module, with a Redis provider, and deprecated the older Cache Module. Use it for read-heavy data such as product listings; with more than one Medusa instance, Redis lets them share one cache. The Caching Module docs give the current setup and any feature flag it needs. A cache hides a slow query; it does not fix the query, so measure first.
What to know before you commit
Indexes cost writes. Every insert or update to an indexed table also updates the index. For most stores, price writes are rare and reads are constant, so a needed index pays for itself; bulk price imports feel it most.
Upgrades move the ground. The fix for #16232 shipped in a minor release. Read the release notes for the cart and pricing workflows before you build your own workaround.
Migrations can hang on deploy. If medusa db:migrate stops with no error, see why medusa db:migrate hangs: the confirmed cause is forced SSL on a non-localhost database host, and a separate ARM64 report (#16011) was closed by the stale bot on 12 August 2026 without a fix.
| App and database far apart | Every request is slow, even simple reads | Same region and network for server, worker and Postgres |
| Development mode | Timings taken from medusa develop | Measure a production build |
| Large-cart line-item lookup | Add-to-cart and refresh slow down as line count grows | Upgrade to v2.19.0 or later |
| A query scanning a large table | EXPLAIN ANALYZE shows a Seq Scan on a big table | One targeted index, built CONCURRENTLY from psql |
| Oversized storefront responses | Large payloads, many relations per request | fields, limit and offset on Store API calls |
Common causes of a slow Medusa v2 cart or checkout, and how to tell them apart
Common questions about checkout performance
Why is my Medusa v2 checkout slow?
Find the slow request first. If every request is slow, check that the Medusa server and PostgreSQL run in the same region, and that you are timing a production build. If add-to-cart and checkout slow down as carts grow, upgrade to v2.19.0 or later, which fixed a line-item lookup that grew with cart size. Then run EXPLAIN ANALYZE on whatever query is still slow.
How many variants can Medusa v2 handle?
There is no published limit, and the count alone doesn't decide speed. What a request costs depends on how many variants and relations it loads, how far the database is, and your Medusa version. Ask for only the fields a page needs, page through variants, and measure with your own catalogue.
Do I need to change Medusa source code to fix checkout performance?
Usually not. Database placement, a production build, an upgrade, a targeted index, smaller Store API requests and the Caching Module are all outside Medusa's core. Patch core only if you have measured a problem that no release fixes yet.
Will a new database index slow down price updates?
A little. Each write to the table also updates the index. For most stores price updates are rare and reads constant, so an index that fixes a measured slow query is worth it. Bulk price imports feel the cost most.
How do I check whether my Medusa store needs an index?
Log the SQL behind the slow request and run EXPLAIN ANALYZE on it. A "Seq Scan" on a large table that the query filters on is the case for an index. Check the existing indexes first with \d <table> in psql; the v2 pricing tables already have several.
Should I use Redis or in-memory caching?
For one Medusa instance, in-process caching is simplest. With several instances behind a load balancer, use the Caching Module's Redis provider so they share one cache. The Caching Module arrived in v2.11 and replaced the deprecated Cache Module.
What Medusa version does this guide apply to?
Medusa v2. The large-cart fix is in v2.19.0 and later; the latest release when we checked on 12 October 2026 was v2.21.2. The table names come from the Pricing Module models in that release.
A slow checkout costs sales, so treat it as a measurement job. Find the slow request, then the slow step or query inside it, and fix that: placement, build mode, version, one index, or a smaller request.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 4 August 2026
Worked with us? Leave a Google review