Variant Events

Documentation for variant-related webhook 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
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_group": {
      "id": "123e4567-e89b-12d3-a456-426614174008",
      "product_id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "Blue",
      "slug": "blue",
      "created_at": "2024-02-12T10:00:00Z",
      "updated_at": "2024-02-15T14:30:00Z"
    },
    "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
    },
    "is_archive": false,
    "shipping_attributes": ["fragile", "oversized"],
    "listings": {
      "static": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174006",
          "slug": "static-listing"
        }
      ],
      "smart": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174007",
          "slug": "smart-listing"
        }
      ]
    }
  }
}

Field Descriptions

Field	Type	Description
`product_number`	string	Parent product number
`product_id`	string	Parent product ID
`product_slug`	string	Parent product slug
`variant_group`	object \| omitted	Present when the variant belongs to a variant group: `id`, `product_id`, `name`, `slug`, `created_at`, `updated_at`. Omitted when ungrouped. If only the group id could be resolved, `name` and `slug` may be empty.
`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, archived)
`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
`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
`listings`	object	Static and smart listing references

variant.deleted and product_variant_status.changed payloads do not include variant_group.

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

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

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

Field	Type	Description
`product_id`	string	Unique identifier of the parent product
`product_number`	string	Product number of the parent product
`variant_id`	string	Unique identifier of the variant
`variant_number`	string	Variant number
`timestamp`	string	ISO 8601 timestamp when the status change occurred
`old_status`	string	Previous status of the variant
`new_status`	string	New status of the variant