Promotions - Models Documentation

Location: api/nextango/apps/promotions/models.py Last Updated: 2026-07-08

Overview

The Promotions domain has two discount mechanisms sharing the same discount vocabulary. PromoCode is a customer-entered code, standalone or grouped under a PromotionalCampaign. Promotion is an auto-apply discount evaluated against every cart with no code required. Both use the same discount_effect / applies_to JSON shapes, and both feed the shared clamp engine in services.py that bounds total discount to the cart subtotal.

Four immutable ledger models back the domain's usage counters and analytics: PromoUsageLedger, CampaignConversion, ABTestConversionLedger, and SaleTransactionAppliedPromotion. Row existence in a ledger is authoritative for whether the corresponding counter increment happened for a given transaction, which makes the increment safe to retry from Celery.

All models except SaleTransactionAppliedPromotion inherit from SanityIntegratedModel (bidirectional Sanity sync) and AuditableMixin (created_at, updated_at, created_by, updated_by). Fields on Sanity-synced models are snake_case in Django and camelCase in the corresponding Sanity schema; the sync layer translates between the two.

PromotionalCampaign

Purpose: Groups one or more PromoCode records (and ABTest records) under a shared marketing campaign with its own date range, store targeting, and performance metrics.

Base class: SanityIntegratedModel, AuditableMixin

Fields

Cross-links: PromotionalCampaignSerializer, PromotionService.get_active_campaigns_for_store

PromoCode

Purpose: Customer-entered discount code with a modular discount effect, application scope, usage limits, and store applicability.

Base class: SanityIntegratedModel, AuditableMixin

Fields

Usage increment: current_usage_count is incremented only after a matching row is written to PromoUsageLedger for the transaction. See PromoUsageLedger below. Applying a code to a cart does not increment the count.

Cross-links: PromoCodeSerializer, PromotionService._calculate_promo_discount

ABTest

Purpose: A/B testing framework tracking variant impressions, conversions, and statistical significance for campaign optimization.

Base class: SanityIntegratedModel, AuditableMixin

Fields

Methods

record_impression(variant) and record_conversion(variant) increment the matching counter using a database-level F() expression (ABTest.objects.filter(pk=self.pk).update(...)), which avoids a read-modify-write race under concurrent requests. variant is 'a' or 'b', case-insensitive; any other value is logged as a warning and ignored.

Cross-links: ABTestSerializer, record-impression / record-conversion actions

Promotion

Purpose: Auto-apply discount evaluated against every cart at checkout time, with no customer-entered code. Authored in Sanity, synced to Django, evaluated against cart contents and inventory.

Base class: SanityIntegratedModel, AuditableMixin Table: promotion

Fields

Checkout evaluation

PromotionService._collect_fired_promotions() filters active Promotion records against a transaction: date range validity, store scope, and an inventory gate (stock must exceed zero for standard discounts, or exceed buy_quantity + get_quantity for BOGO types). Stackable promotions all apply; non-stackable promotions compete on post-clamp discount contribution and the best one wins. See the clamp engine for how the resulting discount amount is computed against the cart.

Cross-links: PromotionSerializer, PromotionViewSet

SaleTransactionAppliedPromotion

Purpose: Immutable snapshot of each auto-apply Promotion applied to a transaction. Preserves the promotion's state at the moment of checkout even if the original Promotion record is later modified or deleted.

Base class: plain Django model (not Sanity-synced) Table: promotion_applied_transaction

Fields

Constraints: UniqueConstraint(transaction, promotion_snapshot_id), one row per promotion per transaction.

Rows are never updated after creation and are used by refund calculations (itemized refund amounts) and analytics (PromotionAnalyticsService.get_auto_promotion_performance, grouped by promotion_snapshot_id).

Cross-links: Analytics Service, Transactions Domain

PromoUsageLedger

Purpose: Audit-trail row per (promo_code, sale_transaction) usage increment. Row existence is authoritative for whether PromoCode.current_usage_count was incremented for a given transaction.

Base class: TimestampedModel Table: promo_usage_ledger

Constraints: UniqueConstraint(promo_code, sale_transaction), the database-level dedup backstop that makes the Celery-driven usage increment safe to retry.

CampaignConversion

Purpose: Audit-trail row per (campaign, sale_transaction) conversion. Row existence is authoritative for whether PromotionService.track_campaign_conversion() was invoked for a given transaction.

Base class: TimestampedModel Table: campaign_conversion

Constraints: UniqueConstraint(campaign, sale_transaction).

ABTestConversionLedger

Purpose: Audit-trail row per (ab_test, sale_transaction) conversion. Row existence is authoritative for whether ABTest.record_conversion() was invoked for a given test/transaction pair.

Base class: TimestampedModel Table: ab_test_conversion_ledger

Constraints: UniqueConstraint(ab_test, sale_transaction).

Model Relationships

PromotionalCampaign ←──M2M──→ PromoCode ──FK──→ PromoUsageLedger ──FK──→ SaleTransaction
        │
        ├──M2M──→ ABTest ──FK──→ ABTestConversionLedger ──FK──→ SaleTransaction
        │
        └──FK──→ CampaignConversion ──FK──→ SaleTransaction

Promotion ──M2M──→ PromotionalCampaign
Promotion ──FK──→ SaleTransactionAppliedPromotion ──FK──→ SaleTransaction

Related Documentation

• Services - PromotionService business logic and the clamp engine
• Signals - Sanity sync
• Views - REST API endpoints
• README - Domain overview