TWIGZ Backend API Documentation

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

name

string

required

Product name (1-100 characters)

description

string

Product description (up to 1000 characters)

category

Id<'categories'>

required

Category ID for the product

price

number

required

Product price in USD

cost

number

Product cost for profit calculations

stock

number

Available stock quantity

stockAlert

number

Stock alert threshold

prepTime

number

Preparation time

prepTimeUnit

string

Time unit: minutes, hours, or days

isActive

boolean

required

Product availability status

primaryImage

Id<'_storage'>

required

Primary product image storage ID

images

Array<Id<'_storage'>>

Additional product images

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"]
});

const productId = await convex.mutation("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"]
});

import requests

response = requests.post(
    f"{CONVEX_URL}/api/mutation",
    json={
        "path": "shared.products.createProduct",
        "args": {
            "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"]
        }
    },
    headers={"Authorization": f"Bearer {token}"}
)

product_id = response.json()

"p123456789"

Update Product

Update an existing product. Only provide the fields you want to change.

productId

Id<'products'>

required

Product ID to update

name

string

Updated product name

description

string

Updated product description

price

number

Updated product price

stock

number

Updated stock quantity

isActive

boolean

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
});

const updatedProduct = await convex.mutation("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);

const products = await convex.query("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.

productId

Id<'products'>

required

Product ID to retrieve

const product = await convex.query(api.shared.products.getProductById, {
  productId: "p123456789"
});

const product = await convex.query("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.

productId

Id<'products'>

required

Product ID to delete

const result = await convex.mutation(api.shared.products.deleteProduct, {
  productId: "p123456789"
});

const result = await convex.mutation("shared.products.deleteProduct", {
  productId: "p123456789"
});

{
  "success": true
}

Error Handling

Product not found

Status Code: 404

{
  "error": "Product not found or you don't have permission to access it"
}

Validation errors

Status Code: 400

{
  "error": "Validation failed",
  "details": {
    "name": "Product name must be between 1 and 100 characters",
    "price": "Price must be a positive number"
  }
}

Unauthorized

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.

Shared Functions

Store Management

Customer Experience

Admin & Platform

HTTP Endpoints

Scheduled Tasks

Database

Development

Products

Overview

Create Product

Update Product

Get Products for Store

Get Product by ID

Delete Product

Error Handling

Best Practices

Image Optimization

Stock Management

SEO Optimization

Performance

​Overview

​Create Product

​Update Product

​Get Products for Store

​Get Product by ID

​Delete Product

​Error Handling

​Best Practices

Image Optimization

Stock Management

SEO Optimization

Performance

Overview

Create Product

Update Product

Get Products for Store

Get Product by ID

Delete Product

Error Handling

Best Practices