--- title: Merchandise - Storefront API description: > A [`ProductVariant`](/docs/api/storefront/2026-01/objects/ProductVariant) that a buyer intends to purchase at checkout. api_version: 2026-01 api_name: storefront type: union api_type: graphql source_url: html: 'https://shopify.dev/docs/api/storefront/latest/unions/Merchandise' md: 'https://shopify.dev/docs/api/storefront/latest/unions/Merchandise.md' --- # Merchandise union A [`ProductVariant`](https://shopify.dev/docs/api/storefront/2026-01/objects/ProductVariant) that a buyer intends to purchase at checkout. ## Possible types * [Product​Variant](https://shopify.dev/docs/api/storefront/latest/objects/ProductVariant) OBJECT A product variant represents a different version of a product, such as differing sizes or differing colors. * available​For​Sale [Boolean!](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) non-null Indicates if the product variant is available for sale. * barcode [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) The barcode (for example, ISBN, UPC, or GTIN) associated with the variant. * compare​At​Price [Money​V2](https://shopify.dev/docs/api/storefront/latest/objects/MoneyV2) The compare at price of the variant. This can be used to mark a variant as on sale, when `compareAtPrice` is higher than `price`. * components [Product​Variant​Component​Connection!](https://shopify.dev/docs/api/storefront/latest/connections/ProductVariantComponentConnection) non-null List of bundles components included in the variant considering only fixed bundles. * first [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come before the specified cursor. *** * currently​Not​In​Stock [Boolean!](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) non-null Whether a product is out of stock but still available for purchase (used for backorders). * grouped​By [Product​Variant​Connection!](https://shopify.dev/docs/api/storefront/latest/connections/ProductVariantConnection) non-null List of bundles that include this variant considering only fixed bundles. * first [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come before the specified cursor. *** * id [ID!](https://shopify.dev/docs/api/storefront/latest/scalars/ID) non-null A globally-unique ID. * image [Image](https://shopify.dev/docs/api/storefront/latest/objects/Image) Image associated with the product variant. This field falls back to the product image if no image is available. * metafield [Metafield](https://shopify.dev/docs/api/storefront/latest/objects/Metafield) Token access required A [custom field](https://shopify.dev/docs/apps/build/custom-data), including its `namespace` and `key`, that's associated with a Shopify resource for the purposes of adding and storing additional information. * namespace [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) ### Arguments The container the metafield belongs to. If omitted, the app-reserved namespace will be used. * key [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) required The identifier for the metafield. *** * metafields [\[Metafield\]!](https://shopify.dev/docs/api/storefront/latest/objects/Metafield) non-null Token access required A list of [custom fields](https://shopify.dev/docs/apps/build/custom-data) that a merchant associates with a Shopify resource. * identifiers [\[Has​Metafields​Identifier!\]!](https://shopify.dev/docs/api/storefront/latest/input-objects/HasMetafieldsIdentifier) required ### Arguments The list of metafields to retrieve by namespace and key. The input must not contain more than `250` values. *** * price [Money​V2!](https://shopify.dev/docs/api/storefront/latest/objects/MoneyV2) non-null The product variant’s price. * product [Product!](https://shopify.dev/docs/api/storefront/latest/objects/Product) non-null The product object that the product variant belongs to. * quantity​Available [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Token access required The total sellable quantity of the variant for online sales channels. * quantity​Price​Breaks [Quantity​Price​Break​Connection!](https://shopify.dev/docs/api/storefront/latest/connections/QuantityPriceBreakConnection) non-null A list of quantity breaks for the product variant. * first [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come before the specified cursor. *** * quantity​Rule [Quantity​Rule!](https://shopify.dev/docs/api/storefront/latest/objects/QuantityRule) non-null The quantity rule for the product variant in a given context. * requires​Components [Boolean!](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) non-null Whether a product variant requires components. The default value is `false`. If `true`, then the product variant can only be purchased as a parent bundle with components. * requires​Shipping [Boolean!](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) non-null Whether a customer needs to provide a shipping address when placing an order for the product variant. * selected​Options [\[Selected​Option!\]!](https://shopify.dev/docs/api/storefront/latest/objects/SelectedOption) non-null List of product options applied to the variant. * selling​Plan​Allocations [Selling​Plan​Allocation​Connection!](https://shopify.dev/docs/api/storefront/latest/connections/SellingPlanAllocationConnection) non-null Represents an association between a variant and a selling plan. Selling plan allocations describe which selling plans are available for each variant, and what their impact is on pricing. * first [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) ### Arguments Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come before the specified cursor. * reverse [Boolean](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * shop​Pay​Installments​Pricing [Shop​Pay​Installments​Product​Variant​Pricing](https://shopify.dev/docs/api/storefront/latest/objects/ShopPayInstallmentsProductVariantPricing) Token access required The Shop Pay Installments pricing information for the product variant. * sku [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) The SKU (stock keeping unit) associated with the variant. * store​Availability [Store​Availability​Connection!](https://shopify.dev/docs/api/storefront/latest/connections/StoreAvailabilityConnection) non-null The in-store pickup availability of this variant by location. * near [Geo​Coordinate​Input](https://shopify.dev/docs/api/storefront/latest/input-objects/GeoCoordinateInput) ### Arguments Used to sort results based on proximity to the provided location. * first [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the first `n` elements from the list. * after [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come after the specified cursor. * last [Int](https://shopify.dev/docs/api/storefront/latest/scalars/Int) Returns up to the last `n` elements from the list. * before [String](https://shopify.dev/docs/api/storefront/latest/scalars/String) Returns the elements that come before the specified cursor. * reverse [Boolean](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) Default:false Reverse the order of the underlying list. *** * taxable [Boolean!](https://shopify.dev/docs/api/storefront/latest/scalars/Boolean) non-null Whether tax is charged when the product variant is sold. * title [String!](https://shopify.dev/docs/api/storefront/latest/scalars/String) non-null The product variant’s title. * unit​Price [Money​V2](https://shopify.dev/docs/api/storefront/latest/objects/MoneyV2) The unit price value for the variant based on the variant's measurement. * unit​Price​Measurement [Unit​Price​Measurement](https://shopify.dev/docs/api/storefront/latest/objects/UnitPriceMeasurement) The unit price measurement for the variant. * weight [Float](https://shopify.dev/docs/api/storefront/latest/scalars/Float) The weight of the product variant in the unit system specified with `weight_unit`. * weight​Unit [Weight​Unit!](https://shopify.dev/docs/api/storefront/latest/enums/WeightUnit) non-null Unit of measurement for weight. * compare​At​Price​V2 [Money​V2](https://shopify.dev/docs/api/storefront/latest/objects/MoneyV2) Deprecated * price​V2 [Money​V2!](https://shopify.dev/docs/api/storefront/latest/objects/MoneyV2) non-nullDeprecated *** ## Fields with this union * [Base​Cart​Line.merchandise](https://shopify.dev/docs/api/storefront/latest/interfaces/BaseCartLine#fields-merchandise) INTERFACE Defines the shared fields for items in a shopping cart. Implemented by [`CartLine`](https://shopify.dev/docs/api/storefront/current/objects/CartLine) for individual merchandise and [`ComponentizableCartLine`](https://shopify.dev/docs/api/storefront/current/objects/ComponentizableCartLine) for grouped merchandise like bundles. Each implementation includes the merchandise being purchased, quantity, cost breakdown, applied discounts, custom attributes, and any associated [`SellingPlan`](https://shopify.dev/docs/api/storefront/current/objects/SellingPlan). * [Cart​Line.merchandise](https://shopify.dev/docs/api/storefront/latest/objects/CartLine#field-CartLine.fields.merchandise) OBJECT An item in a customer's [`Cart`](https://shopify.dev/docs/api/storefront/current/objects/Cart) representing a product variant they intend to purchase. Each cart line tracks the merchandise, quantity, cost breakdown, and any applied discounts. Cart lines can include custom attributes for additional information like gift wrapping requests, and can be associated with a [`SellingPlanAllocation`](https://shopify.dev/docs/api/storefront/current/objects/SellingPlanAllocation) for purchase options like subscriptions, pre-orders, or try-before-you-buy. The [`instructions`](https://shopify.dev/docs/api/storefront/current/objects/CartLine#field-CartLine.fields.instructions) field indicates whether the line can be removed or have its quantity updated. * [Componentizable​Cart​Line.merchandise](https://shopify.dev/docs/api/storefront/latest/objects/ComponentizableCartLine#field-ComponentizableCartLine.fields.merchandise) OBJECT Represents information about the grouped merchandise in the cart. *** ```graphql union Merchandise = ProductVariant ```