Variant Events

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

Variant Created/Updated Event

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

Event Structure

JSON Example

{
  "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,
    "custom_attributes": [
      {
        "key": "size",
        "value": "large"
      },
      {
        "key": "color",
        "value": "blue"
      }
    ],
    "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

Field	Type	Description
product_number	string	Parent product number
product_id	string	Parent product ID
product_slug	string	Parent product slug
variant_name	string	Name of the variant
variant_number	string	Unique variant number
validate_stock	boolean	Whether to validate stock for this variant
status	string	Variant status (active, inactive, draft)
images	array	Variant images
id	string	Unique identifier for the variant
translations	object	Localized content for the variant
description	string	Variant description
image_url	string	URL of the variant's main image
is_active	boolean	Whether the variant is active
custom_attributes	array	Custom key-value attributes
attributes	array	Structured attributes with translations
product_dimensions	object	Physical dimensions of the product
package_dimensions	object	Shipping package dimensions
shipping_attributes	array	Special shipping requirements
brand	object	Brand information
listings	object	Static and smart listing references
collections	array	Associated collections

Variant Deleted Event

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

Event Structure

JSON Example

{
  "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

Field	Type	Description
variant_id	string	Unique identifier of the deleted variant
variant_number	string	Variant number of the deleted variant
product_parent_id	string	ID of the parent product