Read-Only Variants API: Sample Use Cases and Flows

This article presents a few possible use cases and corresponding sample flows that are supported by the Read-Only Variants API.

Manage inventory across multiple products

You need to identify variants that are running low on stock across your entire catalog to prioritize restocking efforts.

To find low-stock variants:

  1. Call Search Variants to find variants that are out of stock but don't have preorders enabled: "inventoryStatus.inStock": false, "inventoryStatus.preorderEnabled": false
  2. Extract the product information and variant details from the response.
  3. Create alerts or reports for your inventory management system using the SKU and product name information.

Build a variant search interface

You want to create a search feature that allows customers to find specific variants by searching product names, then filter results by price range and availability.

To implement variant search:

  1. Use Search Variants with a free-text search query for "cotton t-shirt".
  2. Display the matching variants with their product context (name, images) and variant-specific details (size, color, price).
  3. Use cursor-based pagination to load additional results as customers scroll through the search results.

Sync variant pricing with external systems

You have an external pricing system and need to identify variants that may need price updates by comparing SKUs and current prices.

To extract variant pricing data:

  1. Call Search Variants with merchant data to get cost and profit information: "fields": ["MERCHANT_DATA", "CURRENCY"]
  2. Extract the SKU, current price, cost, and profit margin for each variant.
  3. Compare this data with your external pricing system using the SKU as the key.
  4. Identify discrepancies and use the Products V3 API to update prices as needed.

Create variant analytics dashboard

You want to analyze variant performance by tracking which option combinations are most popular and profitable.

To gather variant analytics data:

  1. Call Query Variants to get all variants with revenue details. You must pass "fields": ["MERCHANT_DATA"] to access cost and profit information.
  2. Group variants by their option choices to analyze performance by size, color, or other attributes.
  3. Calculate metrics like total profit, profit margins, and sales velocity using the cost and profit data.
  4. Identify trends such as which color options generate the highest margins or which size combinations sell most frequently.
Did this help?