List a Product's Variants

Retrieve a list of Product Variants associated with a Product. The variants can be paginated.

Request

Path Params

string

required

ID of the product.

Query Params

fields

string

optional

Comma-separated fields that should be included in the returned product variants.

expand

string

optional

Comma-separated relations that should be expanded in the returned product variants.

offset

integer

optional

The number of product variants to skip when retrieving the product variants.

limit

integer

optional

Limit the number of product variants returned.

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 (Product Variant) {28}]

required

An array of product variants 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.

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"
          }
        }
      ]
    }
  ]
}

🟠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 a Product's Variants

Request

Request samples

Responses