Overview The Products API allows store owners to manage their product catalog with full create, read, update, and delete operations. All products are associated with a specific store and category.
Create Product Product name (1-100 characters)
Product description (up to 1000 characters)
Category ID for the product
Product cost for profit calculations
Time unit: minutes, hours, or days
Product availability status
Primary product image storage ID
Additional product images
TypeScript
JavaScript
Python
const productId = await convex . mutation ( api . shared . products . createProduct , { name: "Pizza Margherita" , description: "Classic Italian pizza with tomatoes, mozzarella, and basil" , category: "k123456789" , price: 15.99 , cost: 8.50 , stock: 100 , stockAlert: 10 , prepTime: 20 , prepTimeUnit: "minutes" , isActive: true , primaryImage: "s123456789" , images: [ "s123456789" , "s987654321" ] });
Update Product Update an existing product. Only provide the fields you want to change.
Updated product description
Updated availability status
const updatedProduct = await convex . mutation ( api . shared . products . updateProduct , { productId: "p123456789" , name: "Pizza Margherita Deluxe" , price: 17.99 , stock: 85 , isActive: true });
{ "_id" : "p123456789" , "name" : "Pizza Margherita Deluxe" , "description" : "Classic Italian pizza with tomatoes, mozzarella, and basil" , "price" : 17.99 , "stock" : 85 , "isActive" : true , "primaryImageUrl" : "https://storage.convex.dev/..." , "imageUrls" : [ "https://storage.convex.dev/..." ], "_creationTime" : 1640995200000 }
Get Products for Store Retrieve all products for the authenticated store owner.
const products = await convex . query ( api . shared . products . getProductsForStore );
[ { "_id" : "p123456789" , "name" : "Pizza Margherita" , "description" : "Classic Italian pizza" , "price" : 15.99 , "stock" : 100 , "isActive" : true , "primaryImageUrl" : "https://storage.convex.dev/..." , "imageUrls" : [ "https://storage.convex.dev/..." ], "category" : { "id" : "k123456789" , "name" : "Food" }, "_creationTime" : 1640995200000 } ]
Get Product by ID Retrieve a specific product by its ID.
const product = await convex . query ( api . shared . products . getProductById , { productId: "p123456789" });
{ "_id" : "p123456789" , "name" : "Pizza Margherita" , "description" : "Classic Italian pizza with tomatoes, mozzarella, and basil" , "price" : 15.99 , "cost" : 8.50 , "stock" : 100 , "stockAlert" : 10 , "prepTime" : 20 , "prepTimeUnit" : "minutes" , "isActive" : true , "primaryImageUrl" : "https://storage.convex.dev/..." , "imageUrls" : [ "https://storage.convex.dev/..." ], "category" : { "id" : "k123456789" , "name" : "Food" }, "store" : { "id" : "j123456789" , "name" : "Mario's Pizza" }, "_creationTime" : 1640995200000 }
Delete Product Delete a product owned by the authenticated store owner.
const result = await convex . mutation ( api . shared . products . deleteProduct , { productId: "p123456789" });
Error Handling
Status Code : 404{ "error" : "Product not found or you don't have permission to access it" }
Status Code : 400{ "error" : "Validation failed" , "details" : { "name" : "Product name must be between 1 and 100 characters" , "price" : "Price must be a positive number" } }
Status Code : 401{ "error" : "Authentication required" }
Best Practices
Image Optimization Upload images in WebP format for better performance. Use multiple sizes for responsive design.
Stock Management Set appropriate stock alerts to avoid overselling. Update stock levels in real-time.
SEO Optimization Use descriptive names and detailed descriptions for better search visibility.
Performance Batch operations when possible. Use pagination for large product catalogs.
Products are automatically indexed for search functionality. Changes to product information are reflected in search results within seconds.
Use the cost field to track profit margins and generate business intelligence reports.
