List Product Variants

GET

/admin/product-variants

Product Variants

Retrieve a list of product variants. The product variants can be filtered by fields such as id. The product variants can also be sorted or paginated.

Response Example

200 - Example 1

{
    "limit": 0,
    "offset": 0,
    "count": 0,
    "variants": [
        {
            "calculated_price": {
                "id": "string",
                "is_calculated_price_price_list": true,
                "is_calculated_price_tax_inclusive": true,
                "calculated_amount": 0,
                "calculated_amount_with_tax": 0,
                "calculated_amount_without_tax": 0,
                "is_original_price_price_list": true,
                "is_original_price_tax_inclusive": true,
                "original_amount": 0,
                "currency_code": "usd",
                "calculated_price": {},
                "original_price": {},
                "original_amount_with_tax": 0,
                "original_amount_without_tax": 0
            },
            "prices": [
                {
                    "id": "string",
                    "title": "string",
                    "currency_code": "usd",
                    "amount": 0,
                    "raw_amount": {},
                    "min_quantity": 0,
                    "max_quantity": 0,
                    "price_set_id": "string",
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z"
                }
            ],
            "id": "string",
            "title": "string",
            "sku": "string",
            "barcode": "string",
            "ean": "string",
            "upc": "string",
            "allow_backorder": true,
            "manage_inventory": true,
            "inventory_quantity": 0,
            "hs_code": "string",
            "origin_country": "string",
            "mid_code": "string",
            "material": "string",
            "weight": 0,
            "length": 0,
            "height": 0,
            "width": 0,
            "variant_rank": 0,
            "options": [
                {
                    "option": {
                        "id": "string",
                        "title": "string",
                        "product": {},
                        "product_id": "string",
                        "metadata": {},
                        "created_at": "2019-08-24T14:15:22Z",
                        "updated_at": "2019-08-24T14:15:22Z",
                        "deleted_at": "2019-08-24T14:15:22Z",
                        "values": [
                            {}
                        ]
                    },
                    "id": "string",
                    "value": "string",
                    "option_id": "string",
                    "metadata": {},
                    "created_at": "2019-08-24T14:15:22Z",
                    "updated_at": "2019-08-24T14:15:22Z",
                    "deleted_at": "2019-08-24T14:15:22Z"
                }
            ],
            "product": {},
            "product_id": "string",
            "created_at": "2019-08-24T14:15:22Z",
            "updated_at": "2019-08-24T14:15:22Z",
            "deleted_at": "2019-08-24T14:15:22Z",
            "metadata": {},
            "inventory_items": [
                {
                    "inventory": {
                        "id": "string",
                        "sku": "string",
                        "origin_country": "string",
                        "hs_code": "string",
                        "requires_shipping": true,
                        "mid_code": "string",
                        "material": "string",
                        "weight": 0,
                        "length": 0,
                        "height": 0,
                        "width": 0,
                        "title": "string",
                        "description": "string",
                        "thumbnail": "string",
                        "metadata": {},
                        "location_levels": [
                            {
                                "id": "string",
                                "created_at": "2019-08-24T14:15:22Z",
                                "updated_at": "2019-08-24T14:15:22Z",
                                "deleted_at": "2019-08-24T14:15:22Z",
                                "inventory_item_id": "string",
                                "location_id": "string",
                                "stocked_quantity": 0,
                                "reserved_quantity": 0,
                                "incoming_quantity": 0,
                                "metadata": {},
                                "inventory_item": {},
                                "available_quantity": 0
                            }
                        ]
                    },
                    "id": "string",
                    "variant_id": "string",
                    "variant": {},
                    "inventory_item_id": "string"
                }
            ]
        }
    ]
}

Request

Authorization

Query Params

fields

string

fields

optional

Comma-separated fields that should be included in the returned data. if a field is prefixed with + it will be added to the default fields, using - will remove it from the default fields. without prefix it will replace the entire default fields.

offset

number

offset

optional

The number of items to skip when retrieving a list.

limit

number

limit

optional

Limit the number of items returned in the list.

order

string

order

optional

The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with -.

string

optional

Search term to filter the product variant's searchable properties.

optional

One of

array[string]

Filter by a variant's ID.

manage_inventory

boolean

manage_inventory

optional

Filter by whether a variant's manage_inventory is enabled.

allow_backorder

boolean

allow_backorder

optional

Filter by whether backorder is allowed for a variant.

$ne

array[string]

optional

Filter by values not equal to this parameter.

Example:

["","",""]

$gt

array[string]

optional

Filter by values greater than this parameter. Useful for numbers and dates only.

Example:

["","",""]

$gte

array[string]

optional

Filter by values greater than or equal to this parameter. Useful for numbers and dates only.

Example:

["","",""]

$lt

array[string]

optional

Filter by values less than this parameter. Useful for numbers and dates only.

Example:

["","",""]

$lte

array[string]

optional

Filter by values less than or equal to this parameter. Useful for numbers and dates only.

Example:

["","",""]

$like

array[string]

optional

Apply a like filter. Useful for strings only.

Example:

["","",""]

$re

array[string]

optional

Apply a regex filter. Useful for strings only.

Example:

["","",""]

$ilike

array[string]

optional

Apply a case-insensitive like filter. Useful for strings only.

Example:

["","",""]

$fulltext

array[string]

optional

Filter to apply on full-text properties.

Example:

["","",""]

$exists

array[string]

optional

Filter by whether a value for this parameter exists (not null).

Example:

["","",""]

$and

array [object]

$and

optional

Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.

Example:

["","",""]

$or

array [object]

$or

optional

Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.

Example:

["","",""]

$in

array[string]

optional

Filter by values in this array.

Example:

["","",""]

$nin

array[string]

optional

Filter by values not in this array.

Example:

["","",""]

$overlap

array[string]

optional

Filter arrays that have overlapping values with this parameter.

Example:

["","",""]

$contains

array[string]

optional

Filter arrays that contain some of the values of this parameter.

Example:

["","",""]

$contained

array[string]

optional

Filter arrays that contain all values of this parameter.

Example:

["","",""]

$eq

array[string]

optional

Example:

["","",""]

$not

array[string]

optional

Example:

["","",""]

Responses

🟢200OK

application/json

Body

The paginated list of product variants.

limit

number

limit

required

The maximum number of items returned.

offset

number

offset

required

The number of items skipped before retrieving the returned items.

count

number

count

required

The total number of items.

variants

array[object (AdminProductVariant) {28}]

required

The product variant's variants.

calculated_price

object

BaseCalculatedPriceSet

optional

The calculated price's details.

prices

array[object (AdminPrice) {11}]

required

The variant's prices.

string

required

The variant's ID.

title

string

title

required

The variant's title.

sku

string

sku

required

The variant's SKU.

barcode

string

barcode

required

The variant's barcode.

ean

string

ean

required

The variant's EAN code.

upc

string

upc

required

The variant's UPC.

allow_backorder

boolean

allow_backorder

required

Whether the variant can be ordered even if it's out of stock.

manage_inventory

boolean

manage_inventory

required

Whether the Medusa application manages the variant's inventory quantity and availablility. If disabled, the variant is always considered in stock.

inventory_quantity

number

inventory_quantity

optional

The variant's inventory quantity. This is only included if you pass in the fields query parameter a +variants.inventory_quantity parameter.

hs_code

string

hs_code

required

The variant's HS code.

origin_country

string

origin_country

required

The variant's origin country.

mid_code

string

mid_code

required

The variant's MID code.

material

string

material

required

The variant's material.

weight

number

weight

required

The variant's weight.

length

number

length

required

The variant's length.

height

number

height

required

The variant's height.

width

number

width

required

The variant's width.

variant_rank

number

variant_rank

optional

The variant's rank among its sibling variants.

options

array[object (AdminProductOptionValue) {8}]

required

The variant's option values.

product

object

optional

product_id

string

product_id

optional

The ID of the product that the variant belongs to.

created_at

string <date-time>

created_at

required

The date the variant was created.

updated_at

string <date-time>

updated_at

required

The date the variant was updated.

deleted_at

string <date-time>

deleted_at

required

The date the variant was deleted.

metadata

object

optional

The variant's metadata, can hold custom key-value pairs.

inventory_items

array[object (AdminProductVariantInventoryItemLink) {5}]

optional

The variant's inventory items.

🟠400Bad Request

🟠401Unauthorized

🟠404Record Not Found

🟠409409

🟠422Parameter Error

🔴500Server Error

Modified at 2025-06-17 04:10:32

Update a Shipping Option