> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # Resource: Products V3 # Type: Product Object # Link: https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/product-object.md ## Description: A product in a Wix Stores catalog. Products can be physical goods that require shipping, or digital content that customers download. Each product has at least one variant, which represents a specific purchasable version with its own pricing, SKU, and inventory. Products with options (like size or color) have multiple variants. Products can be associated with brands and ribbons, enhanced with info sections and extended fields, and organized into categories. ## Schema: ```json Type: Product Object | type: Product Description: A product in a Wix Stores catalog. Products can be physical goods that require shipping, or digital content that customers download. Each product has at least one variant, which represents a specific purchasable version with its own pricing, SKU, and inventory. Products with options (like size or color) have multiple variants. Products can be associated with brands and ribbons, enhanced with info sections and extended fields, and organized into categories. - name: id | type: string | description: Product ID. - name: value | type: string | description: - name: revision | type: string | description: Revision number, which increments by 1 each time the product is updated. To prevent conflicting changes, the current revision must be passed when updating the product. Ignored when creating a product. - name: value | type: string | description: - name: createdDate | type: string | description: Date and time the product was created. - name: seconds | type: string | description: - name: nanos | type: number | description: - name: updatedDate | type: string | description: Date and time the product was updated. - name: name | type: string | description: Product name. Translatable. - name: slug | type: string | description: Product slug. If not provided, the slug is autogenerated based on the product name. - name: url | type: PageUrlV2 | description: URL to the site's product page. > **Note:** Returned only when you pass `"URL"` to the `fields` array in Products API requests. - name: relativePath | type: string | description: The relative path for the page within the site. For example, `/product-page/a-product`. - name: url | type: string | description: The page's full URL. For example, `https://mysite.com/product-page/a-product`. - name: description | type: RichContent | description: Product description using rich content. > **Note:** Returned only when you pass `"DESCRIPTION"` to the `fields` array in Products API requests. See.md Ricos document reference - name: nodes | type: Array | description: Node objects representing a rich content document. - name: type | type: string | description: Node type. Use `APP_EMBED` for nodes that embed content from other Wix apps. Use `EMBED` to embed content in [oEmbed](https://oembed.com/) format. - name: id | type: string | description: Node ID. - name: nodes | type: Array | description: A list of child nodes. - name: style | type: NodeStyle | description: Padding and background color styling for the node. - name: metadata | type: Metadata | description: Object metadata. - name: version | type: number | description: Schema version. - name: createdTimestamp | type: string | description: When the object was created. - name: updatedTimestamp | type: string | description: When the object was most recently updated. - name: id | type: string | description: Object ID. - name: documentStyle | type: DocumentStyle | description: Global styling for header, paragraph, block quote, and code block nodes in the object. - name: headerOne | type: TextNodeStyle | description: Styling for H1 nodes. - name: headerTwo | type: TextNodeStyle | description: Styling for H2 nodes. - name: headerThree | type: TextNodeStyle | description: Styling for H3 nodes. - name: headerFour | type: TextNodeStyle | description: Styling for H4 nodes. - name: headerFive | type: TextNodeStyle | description: Styling for H5 nodes. - name: headerSix | type: TextNodeStyle | description: Styling for H6 nodes. - name: paragraph | type: TextNodeStyle | description: Styling for paragraph nodes. - name: blockquote | type: TextNodeStyle | description: Styling for block quote nodes. - name: codeBlock | type: TextNodeStyle | description: Styling for code block nodes. - name: plainDescription | type: string | description: Product description in HTML. + When provided on create/update, this string must be valid HTML. It's then converted to rich content. + `plainDescription` is ignored when a value is also passed to the `description` field. > **Note:** Returned only when you pass `"PLAIN_DESCRIPTION"` to the `fields` array in Products API requests. - name: visible | type: boolean | description: Whether the product is visible to site visitors. Default: `true` > **Note:** For products without options, updating this field automatically > updates the default variant's visibility to match. > For products with options, the product and variant visibility values are independent. - name: value | type: boolean | description: - name: visibleInPos | type: boolean | description: Whether the product is visible in POS (point of sale). Default: `true` > **Note:** Always `false` for `productType: DIGITAL`. - name: media | type: Media | description: Product media items. For a detailed explanation of product media, see [About Product Media](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/about-product-media.md). - name: main | type: ProductMedia | description: Main media (image, video, etc.) associated with this product. Automatically set to the first item in the media list. - name: altText | type: string | description: Image alt text. - name: displayName | type: string | description: Media display name. Overrides the default media name. Can be passed only when the media is set by a URL in this item's `url` field. - name: mediaType | type: string | description: Media type. - name: thumbnail | type: Thumbnail | description: Media thumbnail. > **Note:** Returned only when you pass `"THUMBNAIL"` to the `fields` array in Products API requests. - name: uploadId | type: string | description: ID used to upload media to Wix Media Manager. - name: itemsInfo | type: MediaItemsInfo | description: All media items. > **Note:** Returned only when you pass `"MEDIA_ITEMS_INFO"` to the `fields` array in Products API requests. - name: items | type: Array | description: All media items associated with this product. The first item in the array is automatically set as the product's main media. - name: seoData | type: SeoSchema | description: Product SEO data. - name: tags | type: Array | description: SEO tag information. - name: type | type: string | description: SEO tag type. Supported values: `title`, `meta`, `script`, `link`. - name: props | type: Struct | description: A `{"key": "value"}` pair object where each SEO tag property (`"name"`, `"content"`, `"rel"`, `"href"`) contains a value. For example: `{"name": "description", "content": "the description itself"}`. - name: meta | type: Struct | description: SEO tag metadata. For example, `{"height": 300, "width": 240}`. - name: children | type: string | description: SEO tag inner content. For example, ` inner content `. - name: custom | type: boolean | description: Whether the tag is a [custom tag](https://support.wix.com/en/article/adding-additional-meta-tags-to-your-sites-pages). - name: disabled | type: boolean | description: Whether the tag is disabled. If the tag is disabled, people can't find your page when searching for this phrase in search engines. - name: settings | type: Settings | description: SEO general settings. - name: preventAutoRedirect | type: boolean | description: Whether the [automatical redirect visits](https://support.wix.com/en/article/customizing-your-pages-seo-settings-in-the-seo-panel) from the old URL to the new one is enabled. Default: `false` (automatical redirect is enabled). - name: keywords | type: Array | description: User-selected keyword terms for a specific page. - name: taxGroupId | type: string | description: [Tax group ID](https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/tax/tax-groups/introduction.md). Used to apply specific tax rates to products. - name: options | type: Array | description: Product options, such as "Size" or "Color". Options define the ways a product can vary. When you provide options, you must also provide the corresponding variants. Each variant must have exactly one choice for each option. For more information, see [About Product Options and Variants](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/about-product-options-and-variants.md). Options are stored as reusable [customization](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/customizations-v3/introduction.md) entities. Pass an existing customization's ID to reuse it, or define options inline and new customization entities are created automatically. - name: id | type: string | description: ID of a customization with `customizationType: PRODUCT_OPTION`. - name: name | type: string | description: Option name. - name: optionRenderType | type: string | description: Option render type. enum: TEXT_CHOICES, SWATCH_CHOICES - name: key | type: string | description: A read-only identifier generated from the option name. Use `key` in the `catalogReference.options` object when [integrating Catalog V3 with eCommerce APIs](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md). - name: modifiers | type: Array | description: Product modifiers. Collect additional information from customers without creating variants. Unlike options, modifiers don't affect inventory or create additional variants. Use them for things like gift messages or engraving text. For more information, see [About Product Options and Variants](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/about-product-options-and-variants.md). Modifiers are stored as reusable [customization](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/customizations-v3/introduction.md) entities. Pass an existing customization's ID to reuse it, or define modifiers inline and new customization entities are created automatically. - name: id | type: string | description: ID of a customization with `customizationType: MODIFIER`. - name: name | type: string | description: Modifier title. - name: modifierRenderType | type: string | description: Modifier render type. enum: FREE_TEXT, TEXT_CHOICES, SWATCH_CHOICES - name: mandatory | type: boolean | description: Whether customer input is required for this modifier. - name: key | type: string | description: A read-only identifier generated from the modifier name. Use `key` in the `catalogReference.options` object when [integrating Catalog V3 with eCommerce APIs](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/e-commerce-integration.md). - name: brand | type: Brand | description: Product [brand](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/brands-v3/introduction.md). + Pass `brand.name` to add a new brand while creating a product. + Pass an existing brand's `id` to assign that brand to the product. - name: id | type: string | description: Brand ID. - name: name | type: string | description: Brand name. - name: infoSections | type: Array | description: Product [info section](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/info-sections-v3/introduction.md). + Pass `infoSection.uniqueName`, `infoSection.title`, and `infoSection.description` to add a new info section while creating a product. + Pass an existing info section's `id` or `uniqueName` to assign that info section to the product. - name: id | type: string | description: Info section ID. - name: uniqueName | type: string | description: Info section unique name. > **Note:** Returned only when you pass `"INFO_SECTION"` to the `fields` array in Products API requests. - name: title | type: string | description: Info section title. > **Note:** Returned only when you pass `"INFO_SECTION"` to the `fields` array in Products API requests. - name: description | type: RichContent | description: Info section description using rich content. > **Note:** Returned only when you pass `"INFO_SECTION_DESCRIPTION"` to the `fields` array in Products API requests. See.md Ricos document reference - name: plainDescription | type: string | description: Info section description in HTML. When provided on create/update, this string must be a valid HTML. It will then be converted to rich content. `plainDescription` is ignored when value is also passed to the `description` field. > **Note:** Returned only when you pass `"INFO_SECTION_PLAIN_DESCRIPTION"` to the `fields` array in Products API requests. - name: ribbon | type: Ribbon | description: Primary [ribbon](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/ribbons-v3/introduction.md) displayed on the product. Use `additionalRibbons` to assign further ribbons beyond the primary one. + Pass `ribbon.name` to add a new ribbon while creating a product. + Pass an existing ribbon's `id` or `name` to assign that ribbon to the product. - name: id | type: string | description: Ribbon ID. - name: name | type: string | description: Ribbon name. - name: directCategoriesInfo | type: ProductCategoriesInfo | description: List of [categories](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/introduction.md) that directly contain this product. Updated automatically when a product is added/removed from a category, when an item is moved within a category, or when a category is deleted. > **Note:** Returned only when you pass `"DIRECT_CATEGORIES_INFO"` to the `fields` array in Products API requests. - name: categories | type: Array | description: A list of categories related to the product. - name: id | type: string | description: Category ID. - name: index | type: number | description: Index location of the product within the category, used for sorting products in a specific category. You can manually arrange up to 100 products per category. For detailed instructions, refer to the [Add and arrange products in a category](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/products-v3/sample-use-cases-and-flows.md#add-and-arrange-products-in-a-category) sample flow. - name: allCategoriesInfo | type: ProductCategoriesInfo | description: List of [categories](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/introduction.md) that directly contain this product, as well as their parent categories. > **Note:** Returned only when you pass `"ALL_CATEGORIES_INFO"` to the `fields` array in Products API requests. - name: mainCategoryId | type: string | description: The ID of the product's primary direct [category](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/introduction.md), which defines the product's breadcrumbs path. For example, if the product's main category is "T-Shirts" (which is a subcategory of "Clothing"), the breadcrumbs path will be "Clothing > T-Shirts". - name: costRange | type: PriceRange | description: Product cost range - minimum and maximum costs of all product variants. > **Note:** Returned only when the following conditions are met: > + You pass `"MERCHANT_DATA"` to the `fields` array in Products API requests. > + Your app has the required `SCOPE.STORES.PRODUCT_READ_ADMIN` permission scope. - name: minValue | type: FixedMonetaryAmount | description: Minimum value. - name: amount | type: string | description: Monetary amount. For example, `"3.99"`, or `"-4.99"` for a negative amount. - name: formattedAmount | type: string | description: Formatted monetary amount. For example, `"$3.99"`. > **Note:** Returned only when you pass `"CURRENCY"` to the `fields` array in Products API requests. - name: maxValue | type: FixedMonetaryAmount | description: Maximum value. - name: inventory | type: Inventory | description: Product inventory info. > **Note:** This field reflects the aggregated inventory status from the default location only. Use the [Inventory Items API](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/inventory-items-v3/introduction.md) to manage inventory for specific locations. Learn more about [inventory management](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/about-inventory-management.md). - name: availabilityStatus | type: string | description: Current availability status. enum: IN_STOCK, OUT_OF_STOCK, PARTIALLY_OUT_OF_STOCK - name: preorderStatus | type: string | description: Current preorder status. enum: ENABLED, DISABLED, PARTIALLY_ENABLED - name: preorderAvailability | type: string | description: Preorder availability status. enum: ALL_VARIANTS, NO_VARIANTS, SOME_VARIANTS - name: productType | type: string | description: Product type: `PHYSICAL` for tangible goods that require shipping, or `DIGITAL` for downloadable content. When passing `productType: PHYSICAL`, you must also pass `physicalProperties`. When passing `productType: DIGITAL`, you can optionally pass `digitalProperties` in each variant. enum: PHYSICAL, DIGITAL - name: handle | type: string | description: A unique human-friendly identifier for the product. Unlike the auto-generated `id`, the handle can be set when creating a product. This is useful when re-importing products from other systems, as it provides a stable identifier across platforms. If not provided during creation, one is automatically generated. Can't be changed after creation. - name: currency | type: string | description: Currency used for the pricing of this product, in [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes) format. Defaults to the currency defined in the site settings, unless specified in the request's `x-wix-currency` header. > **Note:** Returned only when you pass `"CURRENCY"` to the `fields` array in Products API requests. - name: breadcrumbsInfo | type: BreadcrumbsInfo | description: Breadcrumbs of the `mainCategoryId`. Used to navigate to parent [categories](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/introduction.md). Useful for building navigation UI and for SEO purposes. > **Note:** Returned only when you pass `"BREADCRUMBS_INFO"` to the `fields` array in Products API requests. - name: breadcrumbs | type: Array | description: Breadcrumbs. - name: categoryId | type: string | description: Category ID. - name: categoryName | type: string | description: Category name. - name: categorySlug | type: string | description: Category slug. - name: actualPriceRange | type: PriceRange | description: Minimum and maximum current selling prices across all product variants. - name: compareAtPriceRange | type: PriceRange | description: Minimum and maximum compare-at prices (original prices before discounts) across all product variants. Used to show savings to customers. - name: variantsInfo | type: VariantsInfo | description: Product variants. Each variant represents a specific purchasable version of a product defined by option choices. Each variant must reference all product options via its `choices` array, using `optionChoiceNames` in requests. You must explicitly provide each variant when creating products with options. For more information, see [About Product Options and Variants](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/about-product-options-and-variants.md). - name: variants | type: Array | description: List of related variants. - name: id | type: string | description: Variant ID. - name: visible | type: boolean | description: Whether the variant is visible to site visitors. Default: `true` > **Note:** For products without options, updating this field automatically > updates the product's visibility to match. > For products with options, the product and variant visibility values are independent. - name: sku | type: string | description: Variant SKU (stock keeping unit). - name: barcode | type: string | description: Variant barcode. - name: choices | type: Array | description: List of choices that define this variant. Each variant must have exactly one choice for each product option. Use `optionChoiceNames` in all requests where this field is required. For products without options, this array is empty, representing a single "default variant". For more information, see [About Product Options and Variants](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/about-product-options-and-variants.md). - name: price | type: PriceInfo | description: Variant price. - name: revenueDetails | type: RevenueDetails | description: Variant revenue details. > **Note:** Returned only when the following conditions are met: > + You pass `"MERCHANT_DATA"` to the `fields` array in Products API requests. > + Your app has the required `SCOPE.STORES.PRODUCT_READ_ADMIN` permission scope. - name: media | type: ProductMedia | description: Variant media. - name: subscriptionPricesInfo | type: SubscriptionPricesInfo | description: Subscription prices calculated by applying subscription discount to the variant `price.actual_price`. > **Note:** Returned only when you pass `"SUBSCRIPTION_PRICES_INFO"` to the `fields` array in Products API requests. - name: inventoryStatus | type: InventoryStatus | description: Variant inventory status. - name: purchaseEligibility | type: PurchaseEligibility | description: Purchase eligibility settings for the product. - name: userCriteria | type: string | description: enum: MEMBERS_ONLY - name: additionalRibbons | type: Array | description: Additional [ribbons](https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/ribbons-v3/introduction.md) displayed on the product, beyond the primary `ribbon`. Use this field to highlight multiple product attributes at once, for example combining a "New" ribbon with a "Sale" ribbon. Both the primary and additional ribbons are rendered on product cards and on the product page. Each entry follows the same assignment rules as `ribbon`: + Pass `additionalRibbons.name` to add a new ribbon while creating or updating the product. + Pass an existing ribbon's `id` or `name` to assign that ribbon to the product. A ribbon can be assigned to a product at most once: the same ribbon can't appear more than once in `additionalRibbons`, and a ribbon set as `ribbon` can't also appear in `additionalRibbons`. Supports up to 4 additional ribbons per product. - name: extendedFields | type: ExtendedFields | description: Custom extended fields for the product object. [Extended fields](https://dev.wix.com/docs/build-apps/develop-your-app/extensions/backend-extensions/schema-plugins/about-schema-plugin-extensions.md) must be configured in the app dashboard before they can be accessed with API calls. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: tags | type: Tags | description: Tags - name: privateTags | type: TagList | description: Tags that require an additional permission in order to access them, normally not given to site members or visitors. - name: tagIds | type: Array | description: List of tag IDs. - name: publicTags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: subscriptionDetails | type: SubscriptionDetails | description: Product subscriptions. Subscription discounts are defined at the product level but apply to each variant's `actualPrice`. This means the final subscription price varies per variant based on the variant's base price. - name: subscriptions | type: Array | description: Subscriptions. - name: id | type: string | description: Subscription ID. - name: title | type: string | description: Subscription title. - name: description | type: string | description: Subscription description. - name: visible | type: boolean | description: Whether the subscription is visible to site visitors. Default: `true` - name: frequency | type: string | description: Frequency of recurring payment. For example, if `frequency: MONTH` and `billingCycles: 6`; payment will be made monthly for 6 months. - name: interval | type: number | description: Interval of recurring payment. Default: `1`. For example, if `frequency: MONTH`, `billingCycles: 3` and `interval: 2`; payment will be made every 2 months for a total of 6 months. - name: discount | type: SubscriptionDiscount | description: Discount info (optional). For example, a $20 discount would be `amount: 20`, `type: AMOUNT`. - name: allowOneTimePurchases | type: boolean | description: Whether to allow one-time purchases in addition to subscription-based purchases. Default: `false` - name: variantSummary | type: VariantSummary | description: The total number of variants for the product. - name: variantCount | type: number | description: The total number of variants for the product. ```