This article presents possible use cases and corresponding sample flows that you can support. This can be a helpful starting point as you plan your implementation.
This flow demonstrates how to create a product from scratch and manage its core details. This is a good starting point for understanding the Products API.
To create and manage a product:
The return value includes the generated product ID (product.id). Save this ID for subsequent operations.
Add product images by calling Update Product with the media.itemsInfo.items array. Provide image URLs or Wix Media Manager IDs.
Update the product inventory settings by calling Update Product with stock.trackInventory and stock.inventoryStatus fields.
Make the product visible on your storefront by calling Update Product with visible set to true.
Retrieve the complete product details by calling Get Product to verify that the changes were applied correctly.
Before a big sale, a Wix user might want to prepare their store by creating a new category for products on sale, adding ribbons to products to catch visitors' attention, and setting new actual prices and compare-at prices.
To prepare a store for a sale:
Add and arrange products in a category. This allows visitors to filter by this category on the storefront (if Wix users enabled this filter in the Editor). It also lets Wix users control which products visitors see first.
Create a new ribbon by calling Create Ribbon. Save the ribbon ID (ribbon.id) from the return value.
To add the ribbon "Sale" to all products in the category, call Bulk Update Products By Filter with the following request body:
Update the actual prices and compare-at prices. To simplify, consider a single product with 1 variant where the actualPrice is set at $100.
Set a new compareAtPrice. This price indicates what's the price of the product before the sale. Call Bulk Update Product Variants By Filter with a variant containing the desired compareAtPrice and actualPrice:
After this call, the example product has a compareAtPrice of $100 and an actualPrice of $90.
To adjust all actual prices by a specific amount or percentage based on the original actualPrice value, call Bulk Adjust Product Variants By Filter with the following request body:
After this call, the example product has a compareAtPrice of $100 and an actualPrice of $81.
To calculate a new actualPrice from compareAtPrice by applying a discount, call Bulk Adjust Product Variants By Filter with actualPriceFromCompareAtPrice. For example, to set actualPrice as a 20% discount from compareAtPrice, use the following request body:
After this call, the example product has a compareAtPrice of $100 and an actualPrice of $80.
To set the same exact actualPrice for all variants of all products, call Bulk Update Product Variants By Filter with a variant containing the desired actualPrice:
After this call, the example product has a compareAtPrice of $100 and an actualPrice of $75.
The Product object includes predefined fields that can't be removed or renamed. However, there may be instances where you need to add additional fields to accommodate specific flows or use cases for your app.
For example, consider a real estate app that needs to store information about the total area and the type of unit (such as whether it's an apartment or a house). You can achieve this using the extendedFields field of the Product object.
Before continuing, you may want to review the documentation on data extensions or schema plugins.
Follow the guide to extend an existing object to create an extension of type "Stores Catalog Product" in the app dashboard. Be sure to note the namespace of your app, as you'll need it for the next steps. For this example, assume the namespace is @real-estate-app/real-estate-app.
In the JSON Editor, enter the following value:
This defines 2 fields: areaInSqm, which includes minimum value validation, and unitType, which includes maximum length validation. Both fields can be read and written by your app as well as by Wix users.
Save your extension. According to the guide to extend an existing object, you must have your app approved before you can continue with testing.
Once your app is approved, click Test Your App and select a site where you want to install it. Be sure to grant the app permissions to read and write to the stores catalog.
You can now create a product with extended fields by calling Create Product or update an existing product by calling Update Product. In your request, include the extendedFields object with your namespace and the relevant field values.
extendedFields object with your namespace.