Products - Serializers Documentation

Location: api/nextango/apps/products/serializers.py Last Updated: 2026-07-06

Overview

The products serializers connect the products app models to the REST API and handle inbound Sanity webhook payloads. Catalog serializers (Brand, ProductType, Category, Collection, Attribute) mirror their Sanity schemas field for field. ProductSerializer and InventoryLevelSerializer accept Sanity webhook data, converting camelCase keys to snake_case model fields and unwrapping reference objects to Django records. ProductVariantSerializer resolves store-scoped inventory from InventoryLevel and exposes bounded quantity signals for the storefront.

Serializers

BrandSerializer

Exposes: Brand Purpose: Brand serialization with exact Sanity schema matching for bidirectional sync.

ProductTypeSerializer

Exposes: ProductType Purpose: Product type serialization with its parent category relationship.

CategorySerializer

Exposes: Category Purpose: Category serialization with its collections JSONField.

CollectionSerializer

Exposes: Collection Purpose: Collection serialization with associated product types.

ProductVariantSerializer

Exposes: ProductVariant Purpose: Variant serialization with store-scoped inventory resolved from InventoryLevel. Includes parent product fields so the frontend avoids N+1 requests.

Base Fields

Store-Scoped Inventory Fields

All read-only, resolved from the InventoryLevel row that matches the request's store context.

Bounded Quantity Signals

The storefront receives bounded signals instead of raw per-store stock levels. The low-stock threshold and the cart-selector cap are both 10.

Store Context

The serializer resolves the store from the store_id query parameter first, then from the authenticated user's assigned store. Without a store context it uses the first inventory row available for the variant. Inventory rows come from data the viewset prefetches; the serializer queries directly only when no prefetched data exists.

Validation

The API rejects a SKU that already exists on another variant (the database unique constraint on sku backs this check), a sale_price greater than or equal to price, an attributes value that is not an array of objects with attribute and value keys, and a store_location value that is not an array of Sanity reference objects (_ref plus _type: "reference").

ProductSerializer

Exposes: Product Purpose: Product serialization with the dual variant structure: the variants JSONField for exact Sanity sync compliance, and nested variant_records for Django relational access. Accepts Sanity webhook payloads directly.

Base Fields

Computed Fields

All read-only.

Sanity Webhook Handling

The serializer accepts raw Sanity payloads. CamelCase keys (shortDescription, baseDimensions, productNotes, basePromoCode) map to their snake_case model fields, slug objects ({"_type": "slug", "current": "value"}) unwrap to the string value, and basePromoCode reference objects unwrap to the _ref ID. Nested baseDimensions keys convert recursively, with Sanity metadata keys (leading underscore) dropped.

Variants JSON Validation

Each entry in the variants array must carry name, sku, price, stockInitial, and digitalInventory. SKUs must be unique within the array, salePrice must be less than price, stockInitial must be an integer, and digitalInventory must be a boolean. attributes and storeLocation entries, when present, must follow the same structures the variant serializer validates.

Save Behavior

Saving a product with a variants payload syncs the JSON to ProductVariant model records: always on create, and on update whenever variants is part of the validated data.

AttributeSerializer

Exposes: Attribute Purpose: Attribute serialization with the Sanity attributeType structure.

attribute_type must be an array with exactly one element, and that element's _type must be attributeTextList (with an options array of strings) or attributeColorSwatch (with a colors array of objects, each carrying a name and a color object with a hex value).

ProductSearchSerializer

Purpose: Validates search request parameters for the product search endpoint. Not bound to a model.

ProductDocumentSerializer

Purpose: Shapes Elasticsearch hits from ProductDocument for search responses. Serializes ES documents, not model instances.

InventoryLevelSerializer

Exposes: InventoryLevel Purpose: Store-scoped inventory serialization covering stock quantities, costing, reorder settings, and analytics. Accepts Sanity webhook payloads.

Identification Fields

Stock Fields

Costing Fields

Inventory Settings

Analytics and System Fields

All read-only: total_transaction_count, total_revenue, created_at_sanity, last_cost_update, last_synced_at, last_updated, created_at, updated_at.

Validation

The API rejects negative stock_on_hand, stock_reserved, reorder_point, or reorder_quantity values, a standard_cost or max_stock_level that is not positive, and a malformed store_location reference array. Cross-field rules: stock_reserved cannot exceed stock_on_hand, reorder_point cannot exceed max_stock_level, store_specific_product requires store_location entries, and on_sale requires a sale_price.

Sanity Webhook Handling

Inbound payloads convert camelCase keys to snake_case through the shared bidirectional field mapper, with Sanity metadata keys (_id, _type, _rev, _createdAt, _updatedAt) dropped. The Sanity createdAt value maps to created_at_sanity (a per-serializer override; the generic mapper would target the wrong field). product and store reference objects resolve to Django records by sanity_id.

Usage Examples

Creating a Product

from apps.products.serializers import ProductSerializer

data = {
    'name': 'Blue T-Shirt',
    'slug': 'blue-t-shirt',
    'short_description': 'Comfortable cotton t-shirt',
    'variants': [
        {
            'name': 'Small',
            'sku': 'TSHIRT-SM-BLU',
            'price': 29.99,
            'stockInitial': 50,
            'digitalInventory': False
        }
    ]
}

serializer = ProductSerializer(data=data)
if serializer.is_valid():
    product = serializer.save()
    # Variants JSON syncs to ProductVariant records on save
else:
    print(serializer.errors)

Store-Specific Variant Lookup

from apps.products.serializers import ProductVariantSerializer

# Request carries ?store_id=<uuid>
variant = ProductVariant.objects.prefetch_related('inventory_levels').get(sku='TSHIRT-SM-BLU')
serializer = ProductVariantSerializer(variant, context={'request': request})

data = serializer.data
print(f"Store inventory: {data['store_inventory']}")
print(f"Available: {data['stock_available']}")
print(f"Reserved: {data['stock_reserved']}")
print(f"Low stock: {data['low_stock']}, max selectable: {data['max_selectable']}")

Inventory Level Update

from apps.products.serializers import InventoryLevelSerializer

inv_level = InventoryLevel.objects.get(variant_sku='TSHIRT-SM-BLU', store=store)
serializer = InventoryLevelSerializer(inv_level, data={'stock_on_hand': 75}, partial=True)

if serializer.is_valid():
    updated = serializer.save()
    print(f"Updated inventory: {updated.stock_on_hand}")
else:
    print(serializer.errors)

Sanity Webhook Processing

from apps.products.serializers import ProductSerializer

# Webhook payload from Sanity
webhook_data = {
    'name': 'Product Name',
    'slug': {'current': 'product-name'},
    'shortDescription': 'Description text',
    'baseDimensions': {'width': 10, 'height': 5},
    'variants': [
        {
            'name': 'Default',
            'sku': 'PROD-001',
            'price': 19.99,
            'stockInitial': 25,
            'digitalInventory': False
        }
    ]
}

serializer = ProductSerializer(data=webhook_data)
if serializer.is_valid():
    product = serializer.save()
    # camelCase keys convert to snake_case, the slug unwraps,
    # and variants sync to ProductVariant records

Related Documentation

• Models: product model definitions
• Views: API endpoints using these serializers
• Services: business logic layer
• Signals: automatic syncing
• Search: the Elasticsearch document these search serializers shape

File Reference

All serializers: api/nextango/apps/products/serializers.py

• BrandSerializer: serializers.py:7-19
• ProductTypeSerializer: serializers.py:22-34
• CategorySerializer: serializers.py:37-49
• CollectionSerializer: serializers.py:52-64
• ProductVariantSerializer: serializers.py:73-340
• ProductSerializer: serializers.py:343-806
• AttributeSerializer: serializers.py:809-903
• ProductSearchSerializer: serializers.py:906-917
• ProductDocumentSerializer: serializers.py:920-947
• InventoryLevelSerializer: serializers.py:950-1179