Product Variants¶

Product variants represent different options of a product such as size, color, or material combinations. The Konigle SDK provides comprehensive support for managing product variants including updating existing variants and removing variants from products.

!!! note "Variant Creation" Product variants cannot be created directly via the variant manager. Variants are created during product creation or product updates using the variants field. See the Products documentation for variant creation examples.

Updating Existing Variants¶

Basic Variant Updates¶

Update pricing, inventory, and metadata for existing variants:

import konigle
from decimal import Decimal
from konigle.models.commerce.product_variant import ProductVariantUpdate

client = konigle.Client(api_key="your-api-key")

# Update variant price and inventory
variant_update = ProductVariantUpdate(
    price=Decimal("34.99"),  # New price
    inventory_quantity=75,   # Update stock
    sku="SHIRT-M-RED-V2"    # Update SKU
)

updated_variant = client.product_variants.update("variant_123456789", variant_update)

print(f"Updated variant: {updated_variant.title}")
print(f"New price: {updated_variant.price}")
print(f"Stock level: {updated_variant.inventory_quantity}")
print(f"Updated SKU: {updated_variant.sku}")

Pricing Updates¶

from decimal import Decimal
from konigle.models.commerce.product_variant import ProductVariantUpdate

# Update variant pricing with compare-at price for discounts
pricing_update = ProductVariantUpdate(
    price=Decimal("24.99"),         # Sale price
    compare_at_price=Decimal("34.99"), # Original price
    cost=Decimal("12.50")           # Cost of goods
)

updated_variant = client.product_variants.update("variant_123456789", pricing_update)

print(f"Sale price: {updated_variant.price}")
print(f"Original price: {updated_variant.compare_at_price}")
print(f"Discount: {updated_variant.compare_at_price - updated_variant.price}")

Inventory Management¶

# Update inventory settings
inventory_update = ProductVariantUpdate(
    inventory_quantity=0,           # Out of stock
    inventory_policy="continue"     # Allow sales when out of stock
)

updated_variant = client.product_variants.update("variant_123456789", inventory_update)

print(f"Stock level: {updated_variant.inventory_quantity}")
print(f"Inventory policy: {updated_variant.inventory_policy}")

Shipping Information¶

# Update weight and shipping details
shipping_update = ProductVariantUpdate(
    weight=0.5,                    # Weight in default unit
    weight_unit="kg",              # Weight unit
    grams=500,                     # Weight in grams for calculations
    taxable=True                   # Subject to tax
)

updated_variant = client.product_variants.update("variant_123456789", shipping_update)

print(f"Weight: {updated_variant.weight} {updated_variant.weight_unit}")
print(f"Grams: {updated_variant.grams}g")
print(f"Taxable: {updated_variant.taxable}")

Metadata Updates¶

# Update variant title and handle
metadata_update = ProductVariantUpdate(
    title="Premium T-Shirt - Medium / Red / Cotton",
    handle="premium-tshirt-m-red-cotton",
    barcode="1234567890123"
)

updated_variant = client.product_variants.update("variant_123456789", metadata_update)

print(f"Title: {updated_variant.title}")
print(f"Handle: {updated_variant.handle}")
print(f"Barcode: {updated_variant.barcode}")

SEO Updates¶

from konigle.models import SEOMeta
from konigle.models.commerce.product_variant import ProductVariantUpdate

# Update SEO metadata for variant
seo_update = ProductVariantUpdate(
    seo_meta=SEOMeta(
        title="Premium Cotton T-Shirt in Red - Medium Size",
        description="High-quality cotton t-shirt in vibrant red color, medium size. Perfect for casual wear.",
        keywords="t-shirt, cotton, red, medium, premium, casual wear",
        og_title="Premium Red T-Shirt - Medium",
        og_description="Comfortable premium cotton t-shirt in red"
    )
)

updated_variant = client.product_variants.update("variant_123456789", seo_update)
print(f"SEO title: {updated_variant.seo_meta.title}")

Variant Content Updates¶

# Update variant-specific content (EditorJS format)
content_update = ProductVariantUpdate(
    content={
        "time": 1672531200000,
        "blocks": [
            {
                "type": "paragraph",
                "data": {
                    "text": "This red variant features premium cotton fabric with enhanced durability."
                }
            },
            {
                "type": "header",
                "data": {
                    "text": "Size M Specifications",
                    "level": 3
                }
            },
            {
                "type": "list",
                "data": {
                    "style": "unordered",
                    "items": [
                        "Chest: 40 inches",
                        "Length: 28 inches",
                        "Shoulder: 16 inches"
                    ]
                }
            }
        ],
        "version": "2.28.0"
    }
)

updated_variant = client.product_variants.update("variant_123456789", content_update)
print("Updated variant-specific content")

Setting Variant Cover Image¶

# Set a specific image as the variant's cover image
image_update = ProductVariantUpdate(
    image="img_variant_cover_123"  # Image ID to use as cover
)

updated_variant = client.product_variants.update("variant_123456789", image_update)
print(f"Set cover image: {updated_variant.image}")

Bulk Variant Updates¶

Update Multiple Variants¶

# Update multiple variants with different data
variant_updates = [
    {
        "id": "variant_small_red",
        "data": ProductVariantUpdate(
            price=Decimal("29.99"),
            inventory_quantity=25
        )
    },
    {
        "id": "variant_medium_red",
        "data": ProductVariantUpdate(
            price=Decimal("31.99"),
            inventory_quantity=30
        )
    },
    {
        "id": "variant_large_red",
        "data": ProductVariantUpdate(
            price=Decimal("33.99"),
            inventory_quantity=20
        )
    }
]

with konigle.Client(api_key="your-api-key") as client:
    updated_variants = []

    for variant_info in variant_updates:
        try:
            updated = client.product_variants.update(
                variant_info["id"],
                variant_info["data"]
            )
            updated_variants.append(updated)
            print(f"Updated {updated.title}: ${updated.price}")

        except Exception as e:
            print(f"Failed to update {variant_info['id']}: {e}")

print(f"Successfully updated {len(updated_variants)} variants")

Listing and Filtering Variants¶

List Variants for a Product¶

from konigle.filters.commerce import ProductVariantFilters

# Get all variants for a specific product
variant_filters = ProductVariantFilters(
    product_id="prod_123456789",
    ordering="position"  # Order by display position
)

variants = client.product_variants.list(filters=variant_filters)

print(f"Found {variants.count} variants")
for variant in variants.payload:
    print(f"- {variant.title}: ${variant.price}")
    print(f"  SKU: {variant.sku}")
    print(f"  Stock: {variant.inventory_quantity}")
    print(f"  Options: {variant.option1}, {variant.option2}")

Search Variants¶

# Search variants by text query
search_filters = ProductVariantFilters(
    q="red medium",  # Search in title, sku, and barcode
    ordering="-created_at"
)

search_results = client.product_variants.list(filters=search_filters)

print(f"Found {search_results.count} variants matching 'red medium'")

Get Specific Variant¶

# Get detailed information about a specific variant
variant = client.product_variants.get("variant_123456789")

print(f"Variant: {variant.title}")
print(f"Product: {variant.product}")
print(f"Price: ${variant.price} {variant.currency}")
print(f"Stock: {variant.inventory_quantity}")
print(f"Options: {variant.option1} / {variant.option2} / {variant.option3}")
print(f"SKU: {variant.sku}")
print(f"Barcode: {variant.barcode}")
print(f"Weight: {variant.weight} {variant.weight_unit}")
print(f"Is default: {variant.is_default_variant}")

if variant.compare_at_price:
    discount = variant.compare_at_price - variant.price
    print(f"Discount: ${discount} (from ${variant.compare_at_price})")

Async Operations¶

All variant operations support async usage:

import asyncio
import konigle

async def manage_variants():
    async with konigle.AsyncClient(api_key="your-api-key") as client:
        # Update variant asynchronously
        update_data = ProductVariantUpdate(
            price=Decimal("29.99"),
            inventory_quantity=100
        )

        updated_variant = await client.product_variants.update(
            "variant_123456789",
            update_data
        )
        print(f"Updated variant: {updated_variant.title}")

        # List variants asynchronously
        filters = ProductVariantFilters(product_id="prod_123456789")
        variants = await client.product_variants.list(filters=filters)

        print(f"Found {variants.count} variants")

        # Get variant details asynchronously
        variant = await client.product_variants.get("variant_123456789")
        print(f"Variant details: {variant.title} - ${variant.price}")

# Run async function
asyncio.run(manage_variants())

Product variants are crucial for offering multiple options to customers. Proper variant management helps maintain accurate pricing, inventory levels, and product organization across your e-commerce store.