{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Premium Software License v2.0",
  "description": "Enhanced annual license with new AI features, advanced analytics, and premium support.",
  "price": 349.99,
  "currency": "USD",
  "productType": "PRODUCT",
  "status": "ACTIVE",
  "stockCount": 150,
  "quantity": 150,
  "weight": null,
  "unit": null,
  "images": [
    "https://devdraft-images.s3.amazonaws.com/products/software-license-v2.jpg",
    "https://devdraft-images.s3.amazonaws.com/products/software-features-v2.jpg"
  ],
  "variations": null,
  "paymentLink": "https://pay.devdraft.ai/550e8400-e29b-41d4-a716-446655440000",
  "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
  "dateAdded": "2024-01-15T10:30:00.000Z",
  "dateUpdated": "2024-01-21T09:15:00.000Z",
  "app": {
    "id": "app_123456789",
    "name": "My Business App"
  },
  "wallet": {
    "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "address": "0x742d35Cc6635C0532925a3b8d",
    "blockchain": "ETHEREUM"
  },
  "changeLog": [
    {
      "field": "price",
      "oldValue": 299.99,
      "newValue": 349.99,
      "timestamp": "2024-01-21T09:15:00.000Z"
    },
    {
      "field": "name",
      "oldValue": "Premium Software License",
      "newValue": "Premium Software License v2.0",
      "timestamp": "2024-01-21T09:15:00.000Z"
    }
  ]
}
The Update Product endpoint enables you to modify existing products in your catalog. You can update any field including pricing, inventory levels, descriptions, images, and status. The endpoint supports partial updates, allowing you to change only specific fields without affecting others.

Endpoint Details

method
string
PUT
url
string
/api/v0/products/{id}
content-type
string
application/json or multipart/form-data (for image updates)
Authentication: Required (API Key & Secret)
Idempotency: Supported (recommended for update operations)

Parameters

id
string
required
Product ID to update
Format: UUID v4
Example: "550e8400-e29b-41d4-a716-446655440000"

Updatable Fields

name
string
Product name (1-200 characters)
Example: "Premium Software License v2"
description
string
Product description (max 2000 characters)
Example: "Enhanced annual license with new features"
price
number
Product price (must be > 0.01)
Example: 349.99
currency
string
3-letter ISO currency code
Example: "EUR"
status
enum
Product availability status
Values: "ACTIVE", "INACTIVE"
stockCount
number
Current stock level
Example: 75
quantity
number
Available quantity
Example: 75
weight
number
Product weight
Example: 0.3
unit
string
Unit of measurement
Example: "kg"
images
array
Array of image URLs (replaces existing images)
Example: ["https://example.com/new-image.jpg"]

Request Examples

curl -X PUT "https://api.devdraft.ai/api/v0/products/550e8400-e29b-41d4-a716-446655440000" \
  -H "x-client-key: YOUR_CLIENT_KEY" \
  -H "x-client-secret: YOUR_CLIENT_SECRET" \
  -H "x-idempotency-key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Premium Software License v2.0",
    "price": 349.99,
    "description": "Enhanced annual license with new AI features, advanced analytics, and premium support."
  }'

Response Format

Success Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Premium Software License v2.0",
  "description": "Enhanced annual license with new AI features, advanced analytics, and premium support.",
  "price": 349.99,
  "currency": "USD",
  "productType": "PRODUCT",
  "status": "ACTIVE",
  "stockCount": 150,
  "quantity": 150,
  "weight": null,
  "unit": null,
  "images": [
    "https://devdraft-images.s3.amazonaws.com/products/software-license-v2.jpg",
    "https://devdraft-images.s3.amazonaws.com/products/software-features-v2.jpg"
  ],
  "variations": null,
  "paymentLink": "https://pay.devdraft.ai/550e8400-e29b-41d4-a716-446655440000",
  "walletId": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
  "dateAdded": "2024-01-15T10:30:00.000Z",
  "dateUpdated": "2024-01-21T09:15:00.000Z",
  "app": {
    "id": "app_123456789",
    "name": "My Business App"
  },
  "wallet": {
    "id": "abcd1234-5678-90ef-ghij-klmnopqrstuv",
    "address": "0x742d35Cc6635C0532925a3b8d",
    "blockchain": "ETHEREUM"
  },
  "changeLog": [
    {
      "field": "price",
      "oldValue": 299.99,
      "newValue": 349.99,
      "timestamp": "2024-01-21T09:15:00.000Z"
    },
    {
      "field": "name",
      "oldValue": "Premium Software License",
      "newValue": "Premium Software License v2.0",
      "timestamp": "2024-01-21T09:15:00.000Z"
    }
  ]
}

Error Responses

{
  "statusCode": 404,
  "message": "Product not found",
  "error": "Not Found",
  "productId": "550e8400-e29b-41d4-a716-446655440000"
}

Business Logic

Update Scenarios

Price Updates

  • Price Increases: Applied immediately to new purchases
  • Price Decreases: May trigger promotional notifications
  • Currency Changes: Affects new transactions only
  • Bulk Updates: Use idempotency keys to prevent duplicates

Inventory Management

  • Stock Increases: Product becomes available if previously out of stock
  • Stock Decreases: Automatic status change to inactive when reaching zero
  • Quantity Updates: Affects availability calculations
  • Restock Operations: Trigger inventory notifications

Status Changes

  • Activation: Makes product available for purchase
  • Deactivation: Hides product from catalog, prevents new purchases
  • Conditional Updates: Some status changes require inventory validation

Advanced Patterns

Gradual Price Increases

// Implement gradual price increases
const scheduleGradualPriceIncrease = async (productId, targetPrice, steps, intervalDays) => {
  const currentProduct = await manager.getProduct(productId);
  const currentPrice = currentProduct.price;
  const totalIncrease = targetPrice - currentPrice;
  const incrementPerStep = totalIncrease / steps;
  
  const schedule = [];
  for (let i = 1; i <= steps; i++) {
    const newPrice = currentPrice + (incrementPerStep * i);
    const scheduleDate = new Date();
    scheduleDate.setDate(scheduleDate.getDate() + (intervalDays * i));
    
    schedule.push({
      date: scheduleDate,
      price: Math.round(newPrice * 100) / 100,
      step: i
    });
  }
  
  return schedule;
};

Inventory Alerts

// Set up automated low stock alerts
const checkAndAlertLowStock = async (productIds, threshold = 10) => {
  const alerts = [];
  
  for (const productId of productIds) {
    const product = await manager.getProduct(productId);
    
    if (product.stockCount !== null && product.stockCount <= threshold) {
      alerts.push({
        productId,
        productName: product.name,
        currentStock: product.stockCount,
        status: product.stockCount === 0 ? 'out-of-stock' : 'low-stock',
        recommended_restock: threshold * 3 // Suggest 3x threshold
      });
    }
  }
  
  return alerts;
};

Bundle Updates

// Update multiple related products
const updateProductBundle = async (bundleProducts, updateData) => {
  const results = await Promise.allSettled(
    bundleProducts.map(productId => 
      manager.updateProduct(productId, updateData, crypto.randomUUID())
    )
  );
  
  return {
    bundleId: crypto.randomUUID(),
    totalProducts: bundleProducts.length,
    successful: results.filter(r => r.status === 'fulfilled').length,
    failed: results.filter(r => r.status === 'rejected').length,
    details: results.map((result, index) => ({
      productId: bundleProducts[index],
      status: result.status,
      data: result.status === 'fulfilled' ? result.value : result.reason
    }))
  };
};

Validation Rules

Field Validation

  • Name: 1-200 characters, required if provided
  • Description: Max 2000 characters
  • Price: Must be > 0.01 if provided
  • Stock Count: Non-negative integer
  • Currency: Valid 3-letter ISO code
  • Status: Must be ‘ACTIVE’ or ‘INACTIVE’

Business Rules

  • Cannot deactivate products with pending transactions
  • Price changes affect only new purchases
  • Stock updates trigger availability recalculation
  • Currency changes require price validation

Concurrent Updates

  • Last-write-wins for most fields
  • Stock updates use optimistic locking
  • Price changes log previous values
  • Status changes require validation

Security Considerations

Access Control

  • Products can only be updated by their owning application
  • API key scope validation for update operations
  • Rate limiting applies to prevent abuse

Data Integrity

  • Idempotency keys prevent duplicate updates
  • Optimistic locking for critical fields
  • Audit trail for all changes
  • Rollback capability for failed operations

Validation Security

  • Input sanitization for all text fields
  • Price manipulation detection
  • Concurrent update conflict resolution
  • Transaction state validation

Next Steps

After updating a product, you can:
  1. Verify Changes: Fetch the product to confirm updates
  2. Update Related Content: Modify associated payment links or invoices
  3. Notify Customers: Send update notifications for price or feature changes
  4. Monitor Performance: Track how updates affect sales metrics
  5. Manage Inventory: Set up automated restocking based on updated thresholds