Aiminaabee

Retrieve Product Variant

Check whether a variant is in stock.

On this page

In this guide, you'll learn how to retrieve a product variant's inventory quantity in a storefront.

How to Retrieve a Product Variant's Inventory Quantity?

To retrieve variants' inventory quantity using either the List Products or Retrieve Products API routes:

  1. Pass in the fields query parameter the value +variants.inventory_quantity.
    • When also retrieving prices, make sure to include *variants.calculated_price in the beginning of the list of fields. For example, ?fields=*variants.calculated_price,+variants.inventory_quantity.
  2. Pass the publishable API key in the header of the request, which you always do when sending a request to the Store API. The inventory quantity is retrieved based on the stock locations of the sales channels that belong to the API key's scope.
    • If you're using the JS SDK, the publishable API key is automatically passed in the header of the requests as explained in the Publishable API Keys guide.

For example:

Important: If you're also passing *variants.calculated_price in fields to get the product variants' prices, make sure to include it in the beginning of the list of fields. For example, ?fields=*variants.calculated_price,+variants.inventory_quantity.

ts

tsCopy
sdk.store.product.retrieve("us", id, {
  fields: `*variants.calculated_price,+variants.inventory_quantity`,
})
.then(({ product }) => {
  product.variants?.forEach((variant) => {
    const isInStock = variant.manage_inventory === false ||
      variant.inventory_quantity > 0


    // ...
  })
})

In this example, you retrieve the product variants' inventory quantity by passing +variants.inventory_quantity in the fields query parameter. This will add a new inventory_quantity field to each variant object.

When is a Variant in Stock?

A variant is in stock if:

  1. Its manage_inventory's value is false, meaning that Aiminaabee doesn't keep track of its inventory.
  2. If its inventory_quantity's value is greater than 0.
    • This property is only available on variants whose manage_inventory is false.
    • If the variant doesn't have inventory levels in the stock location associated with the API's scope, its inventory_quantity will be null.

Full React Example

For example, to show on a product's page whether a variant is in stock in a React-based storefront:

Tip: Learn how to install and configure the JS SDK in the Getting started guide.

tsx

tsxCopy
"use client" // include with Next.js 13+


import { useEffect, useMemo, useState } from "react"
import { HttpTypes } from "@aiminaabeejs/types"
import { sdk } from "@/lib/sdk"


type Props = {
  id: string
}


export default function Product({ id }: Props) {
  const [loading, setLoading] = useState(true)
  const [product, setProduct] = useState<
    HttpTypes.StoreProduct | undefined
  >()
  const [selectedOptions, setSelectedOptions] = useState<Record<string, string>>({})


  useEffect(() => {
    if (!loading) {
      return
    }


    sdk.store.product.retrieve("us", id, {
      fields: `*variants.calculated_price,+variants.inventory_quantity`,
    })
    .then(({ product: dataProduct }) => {
      setProduct(dataProduct)
      setLoading(false)
    })
  }, [loading])


  const selectedVariant = useMemo(() => {
    if (
      !product?.variants ||
      !product.options ||
      Object.keys(selectedOptions).length !== product.options?.length
    ) {
      return
    }


    return product.variants.find((variant) => variant.options?.every(
      (optionValue) => optionValue.value === selectedOptions[optionValue.option_id!]
    ))
  }, [selectedOptions, product])


  const isInStock = useMemo(() => {
    if (!selectedVariant) {
      return undefined
    }


    return selectedVariant.manage_inventory === false ||
      (selectedVariant.inventory_quantity || 0) > 0
  }, [selectedVariant])


  return (
    <div>
      {loading && <span>Loading...</span>}
      {product && (
        <>
          <h1>{product.title}</h1>
          {(product.options?.length || 0) > 0 && (
            <ul>
              {product.options!.map((option) => (
                <li key={option.id}>
                  {option.title}
                  {option.values?.map((optionValue) => (
                    <button
                      key={optionValue.id}
                      onClick={() => {
                        setSelectedOptions((prev) => {
                          return {
                            ...prev,
                            [option.id!]: optionValue.value!,
                          }
                        })
                      }}
                    >
                      {optionValue.value}
                    </button>
                  ))}
                </li>
              ))}
            </ul>
          )}
          {selectedVariant && (
            <span>Selected Variant: {selectedVariant.id}</span>
          )}
          {isInStock !== undefined && (
            <span>
              {isInStock && "In Stock"}
              {!isInStock && "Out of Stock"}
            </span>
          )}
        </>
      )}
    </div>
  )
}

In this example, you retrieve the product variants' inventory quantity by passing +variants.inventory_quantity in the fields query parameter. This will add a new inventory_quantity field to each variant object.

Then, you find the selected variant and show whether it's in stock. The variant is in stock if its manage_inventory property is disabled, or the inventory_quantity is greater than 0.

Tip: Refer to the Select Product Variants guide to learn more about selecting a product variant.