List Product Variants

Retrieve a list of Product Variants. The product variant can be filtered by fields such as id or title. The product variant can also be paginated.

Request

Query Params

string

optional

Filter by product variant IDs.

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 product variants 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 to use for the price selection context.

region_id

string

optional

The ID of the region to use for the price selection context.

currency_code

string

optional

The 3 character ISO currency code to use for the price selection context.

customer_id

string

optional

The ID of the customer to use for the price selection context.

title

string

optional

Filter by title.

inventory_quantity

string

optional

Filter by available inventory quantity

Responses

🟢200OK

application/json

Body

count

integer

required

The total number of items available

offset

integer

required

The number of product variants skipped when retrieving the product variants.

limit

integer

required

The number of items per page

variants

array[object (Priced Product Variant) {35}]

required

An array of product variant details.

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 unqiue 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:

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

{
  "count": 0,
  "offset": 0,
  "limit": 0,
  "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

🟠401User is not authorized. Must log in first

🟠404Not Found Error

🟠409Invalid State Error

🟠422Invalid Request Error

🔴500Server Error

List Product Variants

Request

Request samples

Responses