Medusa
  1. Product Variants
Medusa
  • Back to home
  • Store API
  • Carts
    • Auth
      • Customer Login (JWT)
      • Customer Login (JWT)
      • Check if Email Exists
      • Get Current Customer
      • Customer Log out
      • Customer Login
    • Create Payment Sessions
      POST
    • Refresh a Payment Session
      POST
    • Create a Cart
      POST
    • Complete a Cart
      POST
    • Select a Payment Session
      POST
    • Delete a Payment Session
      DELETE
    • Update a Payment Session
      POST
    • Get a Cart
      GET
    • Update a Cart
      POST
    • Add Shipping Method
      POST
    • Update a Line Item
      POST
    • Delete a Line Item
      DELETE
    • Add a Line Item
      POST
    • Calculate Cart Taxes
      POST
    • Remove Discount
      DELETE
  • Customers
    • Request Password Reset
      POST
    • Get Saved Payment Methods
      GET
    • Add a Shipping Address
      POST
    • Update Customer
      POST
    • Get a Customer
      GET
    • Update a Shipping Address
      POST
    • Delete an Address
      DELETE
    • Create a Customer
      POST
    • Reset Password
      POST
    • List Orders
      GET
  • Gift Cards
    • Get Gift Card by Code
  • Orders
    • 77
      • Claim Order
    • Verify Order Claim
    • Get an Order
    • Look Up an Order
    • Get by Cart ID
  • Order Edits
    • Complete an Order Edit
    • Retrieve an Order Edit
    • Decline an Order Edit
  • Payment Collections
    • Authorize Payment Session
    • Authorize Payment Sessions
    • Refresh a Payment Session
    • Get a PaymentCollection
    • Manage Payment Sessions
    • Create a Payment Session
  • Products
    • Search Products
    • List Products
    • Get a Product
  • Product Variants
    • Get a Product Variant
      GET
    • Get Product Variants
      GET
  • Product Tags
    • List Product Tags
  • Product Categories
    • List Product Categories
    • Get a Product Category
  • Product Collections
    • Get a Collection
    • List Collections
  • Product Types
    • List Product Types
  • Regions
    • List Regions
    • Get a Region
  • Returns
    • Create Return
  • Return Reasons
    • List Return Reasons
    • Get a Return Reason
  • Shipping Options
    • List for Cart
    • Get Shipping Options
  • Swaps
    • Get by Cart ID
    • Create a Swap
  1. Product Variants

Get Product Variants

GET
/store/variants
Store API/Product VariantsProduct Variants
Retrieves a list of product variants. The product variants can be filtered by fields such as id or title. The product variants can also be paginated.
For accurate and correct pricing of the product variants based on the customer's context, it's highly recommended to pass fields such as
region_id, currency_code, and cart_id when available.
Passing sales_channel_id ensures retrieving only variants of products available in the specified sales channel.
You can alternatively use a publishable API key in the request header instead of passing a sales_channel_id.

Request

Query Params
ids
string 
optional
Filter by a comma-separated list of IDs. If supplied, it overrides the id parameter.
id
string 
optional
Filter by one or more IDs. If ids is supplied, it's overrides the value of this parameter.
sales_channel_id
string 
optional
"Filter by sales channel IDs. When provided, only products available in the selected sales channels are retrieved. Alternatively, you can pass a publishable API key in the request header and this will have the same effect."
expand
string 
optional
Comma-separated relations that should be expanded in the returned product variants.
fields
string 
optional
Comma-separated fields that should be included in the returned product variants.
offset
number 
optional
The number of products to skip when retrieving the product variants.
limit
number 
optional
Limit the number of product variants returned.
cart_id
string 
optional
The ID of the cart. This is useful for accurate pricing based on the cart's context.
region_id
string 
optional
The ID of the region. This is useful for accurate pricing based on the selected region.
currency_code
string 
optional
A 3 character ISO currency code. This is useful for accurate pricing based on the selected currency.
title
string 
optional
Filter by title
inventory_quantity
string 
optional
Filter by available inventory quantity

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request GET '/store/variants'

Responses

🟢200OK
application/json
Body
The list of product variants.
variants
array[object (Priced Product Variant) {35}] 
required
An array of product variant descriptions.
id
string 
required
The product variant's ID
Example:
variant_01G1G5V2MRX2V3PVSR2WXYPFB6
title
string 
required
A title that can be displayed for easy identification of the Product Variant.
Example:
Small
product_id
string 
required
The ID of the product that the product variant belongs to.
Example:
prod_01G1G5V2MBA328390B5AXJ610F
product
object  | null 
optional
The details of the product that the product variant belongs to.
sku
string  | null 
required
The unique stock keeping unit used to identify the Product Variant. This will usually be a unique identifer for the item that is to be shipped, and can be referenced across multiple systems.
Example:
shirt-123
barcode
string  | null 
required
A generic field for a GTIN number that can be used to identify the Product Variant.
Example:
null
ean
string  | null 
required
An EAN barcode number that can be used to identify the Product Variant.
Example:
null
upc
string  | null 
required
A UPC barcode number that can be used to identify the Product Variant.
Example:
null
variant_rank
number  | null 
optional
The ranking of this variant
Default:
0
inventory_quantity
integer 
required
The current quantity of the item that is stocked.
Example:
100
allow_backorder
boolean 
required
Whether the Product Variant should be purchasable when inventory_quantity is 0.
Default:
false
manage_inventory
boolean 
required
Whether Medusa should manage inventory for the Product Variant.
Default:
true
hs_code
string  | null 
required
The Harmonized System code of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
Example:
null
origin_country
string  | null 
required
The country in which the Product Variant was produced. May be used by Fulfillment Providers to pass customs information to shipping carriers.
Example:
null
mid_code
string  | null 
required
The Manufacturers Identification code that identifies the manufacturer of the Product Variant. May be used by Fulfillment Providers to pass customs information to shipping carriers.
Example:
null
material
string  | null 
required
The material and composition that the Product Variant is made of, May be used by Fulfillment Providers to pass customs information to shipping carriers.
Example:
null
weight
number  | null 
required
The weight of the Product Variant. May be used in shipping rate calculations.
Example:
null
length
number  | null 
required
The length of the Product Variant. May be used in shipping rate calculations.
Example:
null
height
number  | null 
required
The height of the Product Variant. May be used in shipping rate calculations.
Example:
null
width
number  | null 
required
The width of the Product Variant. May be used in shipping rate calculations.
Example:
null
created_at
string <date-time>
required
The date with timezone at which the resource was created.
updated_at
string <date-time>
required
The date with timezone at which the resource was updated.
deleted_at
string <date-time> | null 
required
The date with timezone at which the resource was deleted.
purchasable
boolean 
optional
Only used with the inventory modules.
A boolean value indicating whether the Product Variant is purchasable.
A variant is purchasable if:
inventory is not managed
it has no inventory items
it is in stock
it is backorderable.
metadata
object  | null 
required
An optional key-value map with additional details
Example:
{"car":"white"}
options
array[object (Product Option Value) {10}] 
optional
The details of the product options that this product variant defines values for.
inventory_items
array[object (Product Variant Inventory Item) {8}] 
optional
The details inventory items of the product variant.
prices
array[object (Money Amount) {15}] 
optional
The details of the prices of the Product Variant, each represented as a Money Amount. Each Money Amount represents a price in a given currency or a specific Region.
original_price
number 
optional
The original price of the variant without any discounted prices applied.
calculated_price
number 
optional
The calculated price of the variant. Can be a discounted price.
original_price_incl_tax
number 
optional
The original price of the variant including taxes.
calculated_price_incl_tax
number 
optional
The calculated price of the variant including taxes.
original_tax
number 
optional
The taxes applied on the original price.
calculated_tax
number 
optional
The taxes applied on the calculated price.
tax_rates
array [object {3}] 
optional
An array of applied tax rates
Example
{
  "variants": [
    {
      "id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
      "title": "Small",
      "product_id": "prod_01G1G5V2MBA328390B5AXJ610F",
      "product": {},
      "sku": "shirt-123",
      "barcode": null,
      "ean": null,
      "upc": null,
      "variant_rank": 0,
      "inventory_quantity": 100,
      "allow_backorder": false,
      "manage_inventory": true,
      "hs_code": null,
      "origin_country": null,
      "mid_code": null,
      "material": null,
      "weight": null,
      "length": null,
      "height": null,
      "width": null,
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "deleted_at": "2019-08-24T14:15:22Z",
      "purchasable": true,
      "metadata": {
        "car": "white"
      },
      "options": [
        {
          "id": "optval_01F0YESHR7S6ECD03RF6W12DSJ",
          "value": "large",
          "option_id": "opt_01F0YESHQBZVKCEXJ24BS6PCX3",
          "option": {},
          "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
          "variant": {},
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "metadata": {
            "car": "white"
          }
        }
      ],
      "inventory_items": [
        {
          "id": "pvitem_01G8X9A7ESKAJXG2H0E6F1MW7A",
          "inventory_item_id": "string",
          "variant_id": "string",
          "variant": {},
          "required_quantity": 1,
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z"
        }
      ],
      "prices": [
        {
          "id": "ma_01F0YESHRFQNH5S8Q0PK84YYZN",
          "amount": 100,
          "min_quantity": 1,
          "max_quantity": 1,
          "price_list_id": "pl_01G8X3CKJXCG5VXVZ87H9KC09W",
          "price_list": {},
          "variant_id": "variant_01G1G5V2MRX2V3PVSR2WXYPFB6",
          "variant": {},
          "region_id": "reg_01G1G5V26T9H8Y0M4JNE3YGA4G",
          "region": {},
          "created_at": "2019-08-24T14:15:22Z",
          "updated_at": "2019-08-24T14:15:22Z",
          "deleted_at": "2019-08-24T14:15:22Z",
          "currency_code": "usd",
          "currency": {
            "symbol": "$",
            "symbol_native": "$",
            "name": "US Dollar",
            "includes_tax": false,
            "code": "usd"
          }
        }
      ],
      "original_price": 0,
      "calculated_price": 0,
      "original_price_incl_tax": 0,
      "calculated_price_incl_tax": 0,
      "original_tax": 0,
      "calculated_tax": 0,
      "tax_rates": [
        {
          "rate": 0,
          "name": "string",
          "code": "string"
        }
      ]
    }
  ]
}
🟠400Client Error or Multiple Errors
🟠404Not Found Error
🟠409Invalid State Error
🟠422Invalid Request Error
🔴500Server Error
Modified at 2024-05-23 07:10:14
Previous
Get a Product Variant
Next
List Product Tags
Built with