Products - Models Documentation

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

Overview

The Products app keeps two representations of every variant:

• Product.variants (JSONField) holds the exact Sanity structure for CMS sync
• ProductVariant (model) is the relational record used for inventory, transactions, and queries

Sanity is the source of truth for product content. Sync runs Sanity to Django through webhooks; Product, ProductVariant, InventoryLevel, and InventoryMovement all disable outbound Django-to-Sanity sync (_outbound_sync_enabled = False). InventoryLevel changes index into Elasticsearch instead. The taxonomy models (Brand, Category, ProductType, Collection, Attribute) sync bidirectionally.

Models

Brand

Base class: SanityIntegratedModel, AuditableMixin Purpose: Product brand with filter visibility control.

Exposed by BrandSerializer (Serializers); read through BrandViewSet (Views).

Category

Base class: SanityIntegratedModel, AuditableMixin Purpose: Product categorization with collection references.

Exposed by CategorySerializer (Serializers).

ProductType

Base class: SanityIntegratedModel, AuditableMixin Purpose: Product type classification within a category.

Exposed by ProductTypeSerializer (Serializers).

Collection

Base class: SanityIntegratedModel, AuditableMixin Purpose: Product collection for merchandising.

Exposed by CollectionSerializer (Serializers).

Product

Base class: SanityIntegratedModel, AuditableMixin Purpose: Main product record mirroring Sanity's product schema, with a derived variants JSON array.

Outbound sync is disabled: products are authored in Sanity and flow to Django via webhooks only.

A composite index on (hidden, name) backs catalog listing queries. The denormalized taxonomy columns let catalog filters use B-tree indexes instead of scanning nested JSON paths; they refresh on create, on full save, and whenever organization is in update_fields.

Variant structure (JSONField)

Each entry in variants carries Sanity's camelCase field names:

{
  "_key": "f63e4c8b",
  "name": "Small - Red",
  "sku": "PROD-SM-RED",
  "upc": "812345678901",
  "featured": false,
  "onSale": true,
  "price": 29.99,
  "salePrice": 24.99,
  "stockInitial": 15,
  "digitalInventory": false,
  "customInventoryManagement": false,
  "reorderPoint": 5,
  "reorderQuantity": 20,
  "maxStockLevel": 100,
  "basePromoCode": {"_ref": "promo_id", "_type": "reference"},
  "attributes": [
    {"attribute": {"_ref": "attr_id"}, "value": "Red"}
  ],
  "dimensions": {"width": 10, "height": 5, "depth": 3, "weight": 0.5},
  "images": ["image1.jpg", "image2.jpg"],
  "storeLocation": [{"_ref": "store_id", "_type": "reference"}]
}

sync_variants_to_model_records(dispatch_inventory_reconcile_async=False)

Syncs the variants JSONField into ProductVariant records. Variants match by Sanity _key (with a SKU fallback for legacy records that predate _key). The method creates new variants, updates existing ones with camelCase-to-snake_case field mapping (onSale to on_sale, stockInitial to stock_initial, storeLocation to store_location), applies dimension inheritance from base_dimensions when a variant has no dimensions of its own, and handles variants removed from Sanity: those with transaction history are soft-deleted, the rest are hard-deleted.

After the sync, each active variant's inventory levels reconcile against its store assignments. With dispatch_inventory_reconcile_async=True (the webhook path), reconciliation fans out to Celery workers after the transaction commits instead of running inline. Non-webhook callers (admin actions, views, services, serializer writes) keep the default inline behavior.

ProductVariant

Base class: SanityIntegratedModel, AuditableMixin Purpose: Relational variant record for inventory, transactions, UPC lookups, and queries.

Variants are inline objects inside the Sanity product document, so they have no standalone outbound sync. They are created and maintained from Product.variants by sync_variants_to_model_records().

Stock seeding behavior

stock_initial (Sanity field stockInitial) is used once, when the variant is created, to seed InventoryLevel.stock_on_hand. After creation, changes to this field do not update InventoryLevel.stock_on_hand; the original value is preserved in InventoryLevel.stock_initial. Adjust live inventory through the InventoryLevel API endpoints.

Properties and methods

effective_price returns sale_price when on_sale and a sale price is set, otherwise price.

is_in_stock is a global, non-store-specific check: digital variants always report in stock; physical variants report stock_initial > 0. It is not the per-store availability signal. "Is this purchasable at store X" goes through the store-availability seam (products/availability.py), which reads live InventoryLevel rows.

get_effective_promo_code_id() resolves the two-tier promo hierarchy: the variant's base_promo_code if set, else the product's, else None. It does not validate against PromoCode scope; the consuming service applies that gate.

reconcile_inventory_levels() reconciles InventoryLevel rows against the variant's current store assignments: it propagates SKU changes, creates or reactivates rows for newly assigned stores (a reactivated row resets stock_on_hand to 0 and requires a physical count), and soft-deletes rows for unassigned stores. Digital variants get no rows; any legacy active row is soft-deleted. When store_specific_product is false the variant targets all active stores.

has_transaction_history() reports whether any SaleLineItem references the variant; can_be_hard_deleted() is its negation. get_custom_deletion_blockers() surfaces that transaction history as an audit blocker for the safe-delete flow. soft_delete_if_needed() is deprecated; use safe_delete(origin='cleanup_worker', hard_delete=True).

Exposed by ProductVariantSerializer (Serializers); operated on by the product services (Services).

Attribute

Base class: SanityIntegratedModel, AuditableMixin Purpose: Product attribute set for filtering and variant differentiation.

The attribute_type array holds exactly one object, either:

{"_type": "attributeTextList", "options": ["Small", "Medium", "Large"]}

or:

{
  "_type": "attributeColorSwatch",
  "colors": [{"name": "Red", "color": {"hex": "#FF0000"}}]
}

type_name returns the _type of that object. options returns the option list for a text list, or {name, hex, value} objects for a color swatch.

Exposed by AttributeSerializer (Serializers).

InventoryLevel

Base class: SanityIntegratedModel, AuditableMixin Purpose: Per-variant, per-store inventory tracking with costing and reorder settings.

Outbound Sanity sync is disabled; changes index into Elasticsearch only.

Identification fields

Uniqueness is (product, variant_sku, store). A partial index on (store, variant_sku) where is_active=True backs store-scoped lookups.

Stock fields

Five quantity-shaped attributes describe per-row stock state. Each tracks a different lifecycle aspect of the same physical stock; select by intent.

Costing and strategy fields

Settings and analytics fields

Properties and methods

stock_status returns inactive, out_of_stock (on hand is 0), low_stock (on hand at or below reorder_point), overstocked (above max_stock_level), or in_stock. needs_reorder and is_overstocked apply the same thresholds for active rows. effective_sale_price returns sale_price only when on_sale.

is_quarantined() reports whether the row is under a compliance hold in any registered vertical batch profile. Verticals register into the _VERTICAL_BATCH_PROFILE_REGISTRATIONS registry (a dict keyed by relation name, models.py:1110-1127) from their own AppConfig.ready(); cannabis registers its cannabis_profile relation from compliance/cannabis/apps.py. The check ORs across every registered relation and returns False when none is registered, which is correct both for non-regulated verticals and for installs without a given vertical's compliance app.

get_custom_deletion_blockers() surfaces blockers the safe-delete flow cannot infer from FK semantics: active checkout reservations (operational), analytics ledger rows (audit), and one audit blocker per registered vertical batch profile, resolved through the same registry so an install without a given vertical's compliance app contributes no blocker for it.

Exposed by InventoryLevelSerializer (Serializers).

InventoryMovement

Base class: SanityIntegratedModel, AuditableMixin Purpose: Append-only audit row for inventory movements.

Django-owned: outbound Sanity sync is disabled and admin display is read-only.

commit and void support the transaction inventory-idempotency flow: sale commits emit commit rows and voids emit void rows. is_incoming and is_outgoing report quantity sign. "Incoming" is a movement direction, not a live counter; cumulative receipts live on InventoryLevel.stock_lifetime_received.

DailyInventorySnapshot

Base class: models.Model Purpose: Pre-aggregated daily inventory state per store, written nightly by the rollup_daily_inventory_snapshot Celery task and read by analytics inventory-trend endpoints.

InventoryAnalyticsLedger

Base class: TimestampedModel Purpose: Audit-trail row per (sale_transaction, inventory_level) analytics counter increment.

Row existence is authoritative for whether InventoryLevel analytics counters were incremented for a given pair; a unique constraint on the pair keeps the deferred analytics task safe under Celery retries.

Model Relationships

Product
├── variant_records (ProductVariant) - One-to-Many
├── inventory_levels (InventoryLevel) - One-to-Many
└── inventory_movements (InventoryMovement) - One-to-Many

ProductVariant
├── product (Product) - Many-to-One
└── inventory_levels (InventoryLevel) - One-to-Many

InventoryLevel
├── product (Product) - Many-to-One
├── variant (ProductVariant) - Many-to-One
├── store (Store) - Many-to-One
└── analytics_ledger (InventoryAnalyticsLedger) - One-to-Many

Category
└── product_types (ProductType) - One-to-Many

Key Design Patterns

Dual structure

Product.variants preserves the exact Sanity shape for webhook sync; ProductVariant records enable foreign keys, indexed queries, and business logic. sync_variants_to_model_records() keeps the two in step, and a post-save cascade keeps derived representations consistent when a variant record changes (Signals).

Dimension inheritance

A variant with no dimensions, or an empty dimensions object, inherits Product.base_dimensions. A variant with its own dimensions keeps them.

Stock seeding immutability

ProductVariant.stock_initial seeds InventoryLevel.stock_on_hand once at creation and is preserved in InventoryLevel.stock_initial. Later changes to the variant field do not touch live stock; adjust inventory through the InventoryLevel API. This prevents accidental inventory overwrites from product updates or webhook syncs.

Store availability seam

Per-store purchasability reads live InventoryLevel data through products/availability.py, not ProductVariant.is_in_stock. Zone-level inventory and par levels live in the zones app and coexist with store-scoped InventoryLevel rows.

Related Documentation

• Serializers - Product serializers and validation
• Views - Product endpoints and filtering
• Services - Product business logic
• Signals - Product sync signals
• Search - Elasticsearch integration
• Examples - Usage examples

File References

All model definitions: api/nextango/apps/products/models.py

• Brand: models.py:9
• Category: models.py:41
• ProductType: models.py:83
• Collection: models.py:125
• Product: models.py:166
• ProductVariant: models.py:569
• Attribute: models.py:1032
• VerticalBatchProfileRegistration dataclass and _VERTICAL_BATCH_PROFILE_REGISTRATIONS registry: models.py:1110-1127
• InventoryLevel: models.py:1130
• InventoryMovement: models.py:1548
• DailyInventorySnapshot: models.py:1895
• InventoryAnalyticsLedger: models.py:1948