Skip to main content

Update Product

This endpoint allows you to update an existing product's details, including its variants, options, and other properties.

🔹 Endpoint Details​

PUT /api/v1/products/{productId}

Path Parameters​

ParameterTypeRequiredDescription
productIdstringYesThe unique identifier of the product to update

🔒 Authentication​

HeaderRequiredDescription
Content-TypeYesMust be application/json
AuthorizationYesFormat: ONLIVESITE Credential:ONLIVEAccessKeyId, Signature=CalculatedSignature

📝 Request Structure​

All fields are optional in the update request. Only provided fields will be updated.

📘 Update Strategies​

  1. Partial Updates

    • Send only fields that need to change
    • Omitted fields remain unchanged
    • Arrays are replaced, not merged

  2. Variant Updates

    • Include variant id to update existing
    • Omit id to create new variant
    • Variants not included remain unchanged

  3. Option Updates

    • Can add new values to options
    • Cannot remove values in use
    • Full option array required when updating

🎯 Request Examples​

Basic Field Update​

{
    "name": "Updated T-Shirt Name",
    "descriptionHtml": "<p>New description</p>",
    "active": false
}

Price Update Across Variants​

{
    "variants": [
        {
            "id": "789e0123-c45b-67d8-e901-234567890000",
            "price": 34.99
        },
        {
            "id": "890f1234-d56c-78e9-f012-345678901111",
            "price": 34.99
        }
    ]
}

Add New Option and Variant​

{
    "name": "Updated Premium T-Shirt",
    "descriptionHtml": "<p>Updated product description</p>",
    "images": [
        "https://example.com/new-image1.webp"
    ],
    "options": [
        {
            "name": "Size",
            "values": ["Small", "Medium", "Large", "XLarge"]
        },
        {
            "name": "Color",
            "values": ["Black", "White", "Red"]
        }
    ],
    "variants": [
        {
            "id": "789e0123-c45b-67d8-e901-234567890000",
            "sku": "TS-BLK-S",
            "price": 34.99,
            "stock": 75,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Small"
                },
                {
                    "name": "Color",
                    "value": "Black"
                }
            ]
        },
        {
            "sku": "TS-RED-XL",
            "price": 34.99,
            "currency": "EUR",
            "stock": 25,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "XLarge"
                },
                {
                    "name": "Color",
                    "value": "Red"
                }
            ],
            "images": [
                "https://example.com/shirt-red-xl.webp"
            ]
        }
    ],
    "active": true,
    "tags": ["premium", "apparel", "updated"]
}

Stock Management​

{
    "variants": [
        {
            "id": "789e0123-c45b-67d8-e901-234567890000",
            "stock": 75
        }
    ]
}

📤 Response Format​

{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Updated Premium T-Shirt",
    "descriptionHtml": "<p>Updated product description</p>",
    "images": [
        "https://example.com/new-image1.webp"
    ],
    "options": [
        {
            "name": "Size",
            "values": ["Small", "Medium", "Large", "XLarge"]
        },
        {
            "name": "Color",
            "values": ["Black", "White", "Red"]
        }
    ],
    "variants": [
        {
            "id": "789e0123-c45b-67d8-e901-234567890000",
            "sku": "TS-BLK-S",
            "price": 34.99,
            "currency": "EUR",
            "stock": 75,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "Small"
                },
                {
                    "name": "Color",
                    "value": "Black"
                }
            ]
        },
        {
            "id": "890f1234-d56c-78e9-f012-345678901111",
            "sku": "TS-RED-XL",
            "price": 34.99,
            "currency": "EUR",
            "stock": 25,
            "selectedOptions": [
                {
                    "name": "Size",
                    "value": "XLarge"
                },
                {
                    "name": "Color",
                    "value": "Red"
                }
            ],
            "images": [
                "https://example.com/shirt-red-xl.webp"
            ]
        }
    ],
    "price": 34.99,
    "stock": 100,
    "active": true,
    "tags": ["premium", "apparel", "updated"],
    "updatedAt": "2025-05-22T10:30:00Z"
}

📘 Response Interpretation​

  1. Updated Fields

    • Only modified fields are shown
    • updatedAt reflects latest change
    • Price/stock recalculated automatically

  2. Variant Changes

    • Updated variants show new values
    • New variants get assigned IDs
    • Unchanged variants remain as is

📘 Notes​

  • Only provided fields will be updated
  • Omitted fields retain their current values
  • Existing variants can be updated by providing their id
  • New variants can be added without an id
  • Options can be extended with new values
  • Each variant must maintain a unique combination of options
  • The product's total stock and price are automatically recalculated

✅ Common Use Cases​

  • 💰 Price Updates: Modify prices across variants
  • 📦 Stock Management: Update inventory levels
  • 🎨 New Options: Add new size or color options
  • 🆕 New Variants: Add variants for new option combinations
  • ⚡ Status Changes: Activate or deactivate products
  • 📝 Content Updates: Modify descriptions and images
  • 🏷️ Categorization: Update product tags or category

🔍 Validation Rules​

  1. Product Updates

    • All fields are optional
    • New values must pass the same validation as create
    • Cannot remove options that are in use by variants
    • Must maintain at least one variant

  2. Variant Updates

    • Price must be positive
    • Stock must be non-negative
    • Option combinations must be unique
    • SKUs must be unique across all variants

  3. Option Updates

    • Can add new values to existing options
    • Cannot remove values used by existing variants
    • Option names must remain unique

❌ Error Responses​

400 Bad Request​

{
  "statusCode": 400,
  "message": "Invalid input",
  "errors": [
    {
      "field": "price",
      "message": "Price must be a positive number"
    }
  ]
}

401 Unauthorized​

{
  "statusCode": 401,
  "message": "Invalid or missing authorization credentials"
}

403 Forbidden​

{
  "statusCode": 403,
  "message": "Insufficient permissions to update this product"
}

404 Not Found​

{
  "statusCode": 404,
  "message": "Product not found"
}

409 Conflict - Duplicate SKU​

{
  "statusCode": 409,
  "message": "A variant with this SKU already exists"
}

409 Conflict - Option In Use​

{
  "statusCode": 409,
  "message": "Cannot remove option that is in use by variants"
}

422 Validation Error​

{
  "statusCode": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "variants",
      "message": "Product must have at least one variant"
    }
  ]
}

🔍 Update Scenarios​

1. Price Changes​

{
    "variants": [
        {
            "id": "variant-id",
            "price": 39.99
        }
    ]
}

Effect: Updates single variant price

2. Add Option Value​

{
    "options": [
        {
            "name": "Size",
            "values": ["Small", "Medium", "Large", "XLarge"]
        }
    ]
}

Effect: Adds new size option

3. Stock Adjustment​

{
    "variants": [
        {
            "id": "variant-id",
            "stock": 100
        }
    ]
}

Effect: Updates variant stock level

4. Product Status​

{
    "active": false
}

Effect: Deactivates product

🔗 Related Endpoints​

💡 Best Practices​

  1. Validation

    • Validate changes before submitting
    • Check option combinations
    • Verify variant SKUs
    • Test price/stock updates

  2. Performance

    • Batch variant updates
    • Minimize update frequency
    • Cache responses
    • Use partial updates

  3. Data Integrity

    • Maintain option consistency
    • Keep SKUs unique
    • Track variant IDs
    • Log significant changes