ProductVariant2

Represents a particular product variant (color / size / etc) in the ecommerce system.

The assumption is that product variants are what actually gets added to the cart when shopping.

Kind	Type
Used in	EstimateAccrual1, ListProducts1, UpdateOrders4, UpdateProducts3

Properties

• id string required

  ID of the product variant in the ecommerce system

  In case of Shopify, this is just a number without gid://shopify/ProductVariant/ prefix. If your system gives similar fixed prefixes to products, we recommend that you strip them as well.

• title string required when creating/updating

  A user-visible name of the variant

  Should be specified in all cases, except when you're merely referencing an existing variant by ID (in which case you'll only specify a single field, id).

• description string optional

  A user-visible description of the variant

  An optional field for those cases when just the title is not enough for your specific loyalty program.

  When updating variants, an empty string preserves the existing description. Pass a non-empty string to update it.

• sku string optional

  Stock Keeping Unit identifier for this variant

  Providing SKUs is optional for most loyalty programs. If you only have one identifier, send it as an id.

  The SKU is a unique identifier typically used by merchants to track inventory at the variant level. Variants often have different SKUs for each size, color, or other attribute combination.

  When updating variants, an empty string preserves the existing SKU. Pass a non-empty string to update it.

• price monetary optional but recommended

  The price of this variant of the product

  If the price is zero, you need to set price_known to true for it to be accepted.

• price_known boolean optional

  A flag required to accept a zero price

• in_stock tristate optional

  Whether this variant is currently in stock

  Accepts three values: true (in stock), false (out of stock), or null (unknown/not specified).

  When updating, omitting this field or passing null preserves the existing value. Pass true or false to explicitly set the stock status.

  When reading products, a null value indicates that stock information has never been provided for this variant.

• localizations array of ProductVariantLocalization1 optional

  Market-specific variant content for multi-region stores

  Allows specifying different titles, descriptions, and alternate titles for different markets.

  Most loyalty programs do not need to send this information, because normally Bubblehouse does not display product or variant titles to the customers.

  When updating variants:

  • null (or omitted) preserves all existing localizations
  • Empty array [] clears all localizations
  • Non-empty array replaces the full set of localizations - any markets not included will be removed

  Within each localization, empty/omitted fields preserve existing values, enabling partial updates.

• deleted boolean optional

  Set to true to delete this variant in our system

  Bubblehouse does not have deletion APIs for most objects; instead, pass deleted: true when updating an object. Note that we won't delete the data immediately, in case there are other objects referencing this one.