Get Product Variant Inventory Quantity

In this guide, you'll learn how to retrieve the available inventory quantity of a product variant in your Medusa application customizations. That includes API routes, workflows, subscribers, scheduled jobs, and any resource that can access the Medusa container.

Understanding Product Variant Inventory Availability#

Product variants have a manage_inventory boolean field that indicates whether the Medusa application manages the inventory of the product variant.

When manage_inventory is disabled, the Medusa application always considers the product variant to be in stock. So, you can't retrieve the inventory quantity for those products.

When manage_inventory is enabled, the Medusa application tracks the inventory of the product variant using the Inventory Module. For example, when a customer purchases a product variant, the Medusa application decrements the stocked quantity of the product variant.

This guide explains how to retrieve the inventory quantity of a product variant when manage_inventory is enabled.

Retrieve Product Variant Inventory#

To retrieve the inventory quantity of a product variant, use the getVariantAvailability utility function imported from @medusajs/framework/utils. It returns the available quantity of the product variant.

For example:

Code
1import { getVariantAvailability } from "@medusajs/framework/utils"2
3// ...4
5// use req.scope instead of container in API routes6const query = container.resolve("query")7
8const availability = await getVariantAvailability(query, {9  variant_ids: ["variant_123"],10  sales_channel_id: "sc_123",11})

A product variant's inventory quantity is set per stock location. This stock location is linked to a sales channel.

So, to retrieve the inventory quantity of a product variant using getVariantAvailability, you need to also provide the ID of the sales channel to retrieve the inventory quantity in.

Parameters#

The getVariantAvailability function accepts the following parameters:

Returns#

The getVariantAvailability function resolves to an object whose keys are the IDs of each product variant passed in the variant_ids parameter.

The value of each key is an object with the following properties:

For example, the object may look like this:

Example result
1{2  "variant_123": {3    "availability": 10,4    "sales_channel_id": "sc_123"5  }6}

Retrieve Sales Channel to Use#

To retrieve the sales channel ID to use in the getVariantAvailability function, you can either:

• Use the sales channel of the request's scope.
• Use the sales channel that the variant's product is available in.

Method 1: Use Sales Channel Scope in Store Routes#

Requests sent to API routes starting with /store must include a publishable API key in the request header. This scopes the request to one or more sales channels associated with the publishable API key.

So, if you're retrieving the variant inventory availability in an API route starting with /store, you can access the sales channel using the publishable_key_context.sales_channel_ids property of the request object:

Code
1import { MedusaStoreRequest, MedusaResponse } from "@medusajs/framework/http"2import { getVariantAvailability } from "@medusajs/framework/utils"3
4export async function GET(5  req: MedusaStoreRequest,6  res: MedusaResponse7) {8  const query = req.scope.resolve("query")9  const sales_channel_ids = req.publishable_key_context.sales_channel_ids10
11  const availability = await getVariantAvailability(query, {12    variant_ids: ["variant_123"],13    sales_channel_id: sales_channel_ids[0],14  })15
16  res.json({17    availability,18  })19}

In this example, you retrieve the scope's sales channel IDs using req.publishable_key_context.sales_channel_ids, whose value is an array of IDs.

Then, you pass the first sales channel ID to the getVariantAvailability function to retrieve the inventory availability of the product variant in that sales channel.

Method 2: Use Product's Sales Channel#

A product is linked to the sales channels it's available in. So, you can retrieve the details of the variant's product, including its sales channels.

For example:

Code
1import { getVariantAvailability } from "@medusajs/framework/utils"2
3// ...4
5// use req.scope instead of container in API routes6const query = container.resolve("query")7
8const { data: variants } = await query.graph({9  entity: "variant",10  fields: ["id", "product.sales_channels.*"],11  filters: {12    id: "variant_123",13  },14})15
16const availability = await getVariantAvailability(query, {17  variant_ids: ["variant_123"],18  sales_channel_id: variants[0].product!.sales_channels![0]!.id,19})

In this example, you retrieve the sales channels of the variant's product using Query.

You pass the ID of the variant as a filter, and you specify product.sales_channels.* as the fields to retrieve. This retrieves the sales channels linked to the variant's product.

Then, you pass the first sales channel ID to the getVariantAvailability function to retrieve the inventory availability of the product variant in that sales channel.