Marketplace Products API: Sample Flows

This article shares some possible use cases you can support. This can be a helpful jumping off point as you plan your implementation.

Create and manage product catalogs

You can publish a dropshipping provider's product catalog to the Wix Marketplace so Wix store owners can discover and sell the products. You need to create products with complete information including media, pricing, and shipping details.

To create and manage a product catalog:

1. Call Create Product with all required parameters including providerInfo, name, media, types, and minimumPrice. The API returns the created product object.
2. Set types for dropshipping products or include wholesale options. This assigns the distribution type on the product record.
3. Provide product media. The first image in the media.items array becomes the main image and appears as the product's main image in Marketplace listings.
4. Specify shipping destinations with minimumShippingCost and shippingTime for each location. These values determine the shipping cost and estimated delivery time shown to Wix store owners.
5. Optionally specify the directCategories parameter. Associating direct categories improves discoverability by assigning the product to specific category IDs.
6. Call Update Product to modify product information, inventory levels, or pricing. This updates the product record and returns the updated product object.
7. Call Bulk Create Products for efficient catalog uploads with up to 100 products per request. The API creates the products in a single request and returns a result entry for each item. Check the itemMetadata.success field for each result to identify failures.
8. Handle bulk operation errors appropriately:
   • For validation errors like invalid data or missing required fields, fix the data and retry only the failed items.
   • For transient errors like temporary service issues, retry the failed items after a delay.
   • Never retry the entire batch - only retry items that failed.
9. Call Delete Product to remove products that are no longer available. This removes the product from the Marketplace and returns a confirmation response.

Organize products with categories and search for better discoverability

You want to organize products into categories for better discoverability and implement search functionality to help Wix store owners find relevant products quickly.

To organize and search products:

1. Call Query Categories to retrieve available Marketplace categories.
2. When you create products, specify directCategories with category IDs. This assigns those categories to the product so it appears under the specified category IDs in searches and category listings.
3. The system populates allCategories with both direct categories and their ancestor categories.
4. Choose the appropriate endpoint for your use case:
   • Use Search Products for product discovery, browsing, and user-facing catalogs. Search provides full-text search with search.expression, aggregations for faceted navigation, and eventually consistent results optimized for performance.
   • Use Query Products for operational tasks requiring real-time accuracy, such as checking current product data or administrative functions. Query provides strongly consistent results but doesn't support full-text search or aggregations.
5. Apply filters using the filter parameter with WQL syntax. See the API Query Language for more information.
6. Sort results using the sort parameter with fields like minimumPrice, createdDate, or name. The API returns results ordered by the specified sort field.
7. Call Bulk Update Product Tags to assign custom tags for organization beyond categories. The operation applies tags to the specified products and returns the results for each updated item.
8. Implement faceted search using aggregations in Search Products to show category counts and price ranges to Wix store owners.