medusa-store/www/apps/cloud/app/cache/page.mdx

import { Prerequisites, Table } from "docs-ui"

export const metadata = {
  title: `Medusa Cache`,
}

# {metadata.title}

In this guide, you'll learn about Medusa Cache.

## What is Medusa Cache?

Medusa Cache is a caching layer that improves your application's performance and reduces costs. It's available to all environments and plans out of the box at no additional cost.

Medusa Cache relies on the existing key/value [Redis](../redis/page.mdx) store already provisioned for environments. Each environment has its own isolated cache.

![Diagram showcasing Redis isolation between environments](https://res.cloudinary.com/dza7lstvk/image/upload/v1750230910/Cloud/redis-cloud_llg83c.jpg)

---

## How Does Medusa Cache Work?

### Enabled by Default

Medusa Cache is enabled by default for all environments and plans if your Medusa project is running [Medusa v2.11.0 or later](https://github.com/medusajs/medusa/releases/tag/v2.11.0). No configuration is required to start using caching.

### Cached Data in API Routes

By using Medusa Cache, data is cached across several business-critical APIs to boost performance and throughput. This includes all cart-related operations, where the following data is cached:

- Regions
- Promotion codes
- Variant price sets
- Variants
- Shipping options
- Sales channels
- Customers

### Integrated into Query

{/* Medusa Cache is built on the new [Caching Module](!resources!/infrastructure-modules/caching). The module has been integrated into [Query](!docs!/learn/fundamentals/module-links/query) so that `query.graph` calls can be cached easily. */}

Medusa Cache is built on the new [Caching Module](#). The module has been integrated into [Query](!docs!/learn/fundamentals/module-links/query) so that `query.graph` calls can be cached easily.

You can enable caching for your custom `query.graph` calls by passing a `cache` option. For example:

```ts
const { data: products } = await query.graph({
  entity: "product",
  fields: ["id", "title", "handle"],
}, {
  cache: {
    enable: true
  }
})
```

This code caches the query result. When the same query is made again, the cached result is returned instead of querying the database.

![Diagram showcasing cache miss and cache hit](https://res.cloudinary.com/dza7lstvk/image/upload/v1759999050/Cloud/medusa-cache-overview_zqpwuo.jpg)

### Automatic Invalidation

By default, data is cached for one hour or until invalidated. Invalidation occurs automatically when related data is created, updated, or deleted.

{/* Learn more about automatic invalidation in the [Caching Module documentation](!resources!/infrastructure-modules/caching/concepts#automatic-cache-invalidation). */}

Learn more about automatic invalidation in the [Caching Module documentation](#).

---

## Performance Benchmark Comparisons

The following benchmark comparisons demonstrate the performance improvements you can expect with Medusa Cache. These were conducted on a Cloud environment with a standard setup.

<Table>
  <Table.Header>
    <Table.Row>
      <Table.HeaderCell className="w-1/2">
        Endpoint
      </Table.HeaderCell>
      <Table.HeaderCell>
        Without Medusa Cache (ms)
      </Table.HeaderCell>
      <Table.HeaderCell>
        With Medusa Cache (ms)
      </Table.HeaderCell>
      <Table.HeaderCell>
        Improvement
      </Table.HeaderCell>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    <Table.Row>
      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
        **Product Operations**
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `GET /store/products`
      </Table.Cell>
      <Table.Cell>
        `354.00`
      </Table.Cell>
      <Table.Cell>
        `83.00`
      </Table.Cell>
      <Table.Cell>
        `~77%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `GET /store/product-categories`
      </Table.Cell>
      <Table.Cell>
        `88.00`
      </Table.Cell>
      <Table.Cell>
        `51.00`
      </Table.Cell>
      <Table.Cell>
        `~42%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `GET /store/products/:id`
      </Table.Cell>
      <Table.Cell>
        `161.00`
      </Table.Cell>
      <Table.Cell>
        `123.00`
      </Table.Cell>
      <Table.Cell>
        `~24%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
        **Cart Operations**
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/carts/:id/line-items`
      </Table.Cell>
      <Table.Cell>
        `697.00`
      </Table.Cell>
      <Table.Cell>
        `427.00`
      </Table.Cell>
      <Table.Cell>
        `~39%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/carts/:id/shipping-methods`
      </Table.Cell>
      <Table.Cell>
        `1002.00`
      </Table.Cell>
      <Table.Cell>
        `670.00`
      </Table.Cell>
      <Table.Cell>
        `~33%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/carts/:id/promotions`
      </Table.Cell>
      <Table.Cell>
        `302.00`
      </Table.Cell>
      <Table.Cell>
        `203.00`
      </Table.Cell>
      <Table.Cell>
        `~33%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `GET /store/carts/:id`
      </Table.Cell>
      <Table.Cell>
        `109.00`
      </Table.Cell>
      <Table.Cell>
        `73.00`
      </Table.Cell>
      <Table.Cell>
        `~33%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/carts/:id`
      </Table.Cell>
      <Table.Cell>
        `909.00`
      </Table.Cell>
      <Table.Cell>
        `656.00`
      </Table.Cell>
      <Table.Cell>
        `~28%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/carts`
      </Table.Cell>
      <Table.Cell>
        `446.00`
      </Table.Cell>
      <Table.Cell>
        `329.00`
      </Table.Cell>
      <Table.Cell>
        `~26%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/carts/:id/complete`
      </Table.Cell>
      <Table.Cell>
        `1357.00`
      </Table.Cell>
      <Table.Cell>
        `1018.00`
      </Table.Cell>
      <Table.Cell>
        `~25%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
        **Order Operations**
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `GET /store/orders/:id`
      </Table.Cell>
      <Table.Cell>
        `119.00`
      </Table.Cell>
      <Table.Cell>
        `81.00`
      </Table.Cell>
      <Table.Cell>
        `~32%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell colSpan={4} className="bg-medusa-bg-subtle">
        **Other Operations**
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `GET /store/regions`
      </Table.Cell>
      <Table.Cell>
        `89.00`
      </Table.Cell>
      <Table.Cell>
        `51.00`
      </Table.Cell>
      <Table.Cell>
        `~43%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `GET /store/shipping-options`
      </Table.Cell>
      <Table.Cell>
        `272.00`
      </Table.Cell>
      <Table.Cell>
        `173.00`
      </Table.Cell>
      <Table.Cell>
        `~36%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/payment-collections`
      </Table.Cell>
      <Table.Cell>
        `238.00`
      </Table.Cell>
      <Table.Cell>
        `160.00`
      </Table.Cell>
      <Table.Cell>
        `~33%`
      </Table.Cell>
    </Table.Row>
    <Table.Row>
      <Table.Cell>
        `POST /store/payment-collections/:id/payments`
      </Table.Cell>
      <Table.Cell>
        `152.00`
      </Table.Cell>
      <Table.Cell>
        `102.00`
      </Table.Cell>
      <Table.Cell>
        `~33%`
      </Table.Cell>
    </Table.Row>
  </Table.Body>
</Table>

---

## Opt-Out of Medusa Cache

If you want to disable Medusa Cache for your Medusa project, you can do so by disabling the `caching` feature flag in `medusa-config.ts`:

```ts title="medusa-config.ts"
module.exports = defineConfig({
  // ...
  featureFlags: {
    caching: false
  }
})
```

This will disable all Medusa Cache functionality in your project.