Skip to main content
This section covers all webhook events related to variants, including variant creation, updates, and deletions.

​
Event Types

The following variant-related events are available:
  • variant.created - Triggered when a new variant is created
  • variant.updated - Triggered when an existing variant is modified
  • variant.deleted - Triggered when a variant is deleted
  • product_variant_status.changed - Triggered when a variant status have changed

​
Variant Created/Updated Event

The variant.created and variant.updated events share the same payload structure.

​
Event Structure

{
  "event_type": "variant.created", // variant.updated
  "payload": {
    "product_number": "PROD-123",
    "product_id": "123e4567-e89b-12d3-a456-426614174000",
    "product_slug": "sample-product",
    "variant_name": "Sample Variant",
    "variant_number": "VAR-123",
    "validate_stock": true,
    "status": "active",
    "id": "123e4567-e89b-12d3-a456-426614174001",
    "images": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174001",
        "url": "https://example.com/images/coffee-maker.jpg",
        "alt": "Premium Coffee Maker",
        "status": "active",
        "title": "Premium Coffee Maker - Main Image",
        "copyright": "© 2024 Your Brand",
        "sort": 1
      }
    ],
    "translations": {
      "variant_name": [
        {
          "country_code": "us",
          "value": "Sample Variant"
        },
        {
          "country_code": "es",
          "value": "Variante de Muestra"
        }
      ],
      "variant_description": [
        {
          "country_code": "us",
          "value": "Sample variant description"
        },
        {
          "country_code": "es",
          "value": "Descripción de la variante"
        }
      ],
      "product_slug_translations": [
        {
          "country_code": "us",
          "value": "sample-product"
        },
        {
          "country_code": "es",
          "value": "producto-muestra"
        }
      ]
    },
    "description": "Sample variant description",
    "image_url": "https://example.com/images/variant.jpg",
    "is_active": true,
    "attributes": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174002",
        "name": "Size",
        "key": "size",
        "template_key": "size_template",
        "values": {
          "size": [
            {
              "id": "123e4567-e89b-12d3-a456-426614174003",
              "key": "large",
              "type": "size",
              "value": "Large",
              "translations": {
                "value": [
                  {
                    "country_code": "us",
                    "value": "Large"
                  }
                ]
              }
            }
          ]
        }
      }
    ],
    "product_dimensions": {
      "width": 10,
      "height": 20,
      "length": 30,
      "depth": 15,
      "weight": 1000,
      "diameter": 5,
      "capacity_milliliter": 500
    },
    "package_dimensions": {
      "width": 15,
      "height": 25,
      "length": 35,
      "depth": 20,
      "weight": 1200,
      "diameter": 10,
      "capacity_milliliter": 0
    },
    "tags": [],
    "is_archive": false,
    "shipping_attributes": ["fragile", "oversized"],
    "brand": {
      "id": "123e4567-e89b-12d3-a456-426614174004",
      "name": "Sample Brand",
      "series": {
        "id": "123e4567-e89b-12d3-a456-426614174005",
        "name": "Premium Series"
      }
    },
    "listings": {
      "static": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174006",
          "slug": "static-listing"
        }
      ],
      "smart": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174007",
          "slug": "smart-listing"
        }
      ]
    },
    "collections": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174008",
        "slug": "summer-collection",
        "title": "Summer Collection",
        "status": "active",
        "translation": {
          "title": [
            {
              "country_code": "us",
              "value": "Summer Collection"
            }
          ],
          "slug": [
            {
              "country_code": "us",
              "value": "summer-collection"
            }
          ]
        }
      }
    ]
  }
}

​
Field Descriptions

FieldTypeDescription
product_numberstringParent product number
product_idstringParent product ID
product_slugstringParent product slug
variant_namestringName of the variant
variant_numberstringUnique variant number
validate_stockbooleanWhether to validate stock for this variant
statusstringVariant status (active, inactive, draft, archived)
imagesarrayVariant images
idstringUnique identifier for the variant
translationsobjectLocalized content for the variant
descriptionstringVariant description
image_urlstringURL of the variant’s main image
is_activebooleanWhether the variant is active
attributesarrayStructured attributes with translations
product_dimensionsobjectPhysical dimensions of the product
package_dimensionsobjectShipping package dimensions
shipping_attributesarraySpecial shipping requirements
brandobjectBrand information
listingsobjectStatic and smart listing references
collectionsarrayAssociated collections

​
Variant Deleted Event

The variant.deleted event is triggered when a variant is removed from the system.

​
Event Structure

{
  "event_type": "variant.deleted",
  "payload": {
    "variant_id": "123e4567-e89b-12d3-a456-426614174000",
    "variant_number": "VAR-123",
    "product_parent_id": "123e4567-e89b-12d3-a456-426614174001"
  }
}

​
Field Descriptions

FieldTypeDescription
variant_idstringUnique identifier of the deleted variant
variant_numberstringVariant number of the deleted variant
product_parent_idstringID of the parent product

​
Variant Status Changed

The product_variant_status.changed event is triggered when a variant’s status is modified.

​
Event Structure

{
  "event_type": "product_variant_status.changed",
  "payload": {
    "product_id": "123e4567-e89b-12d3-a456-426614174000",
    "product_number": "PROD-123",
    "variant_id": "123e4567-e89b-12d3-a456-426614174001",
    "variant_number": "VAR-123",
    "timestamp": "2024-01-15T10:30:00Z",
    "old_status": "draft",
    "new_status": "active"
  }
}

​
Field Descriptions

FieldTypeDescription
product_idstringUnique identifier of the parent product
product_numberstringProduct number of the parent product
variant_idstringUnique identifier of the variant
variant_numberstringVariant number
timestampstringISO 8601 timestamp when the status change occurred
old_statusstringPrevious status of the variant
new_statusstringNew status of the variant