---
title: Variant Events
description: Documentation for variant-related webhook events
sidebar:
  label: 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
- `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

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

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

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