OrderEvent

File: app/core/models/orders.py

Represents customer purchase events synced from external commerce providers.

Key fields

Field	Description
id	Internal ID
provider_id / provider_type	External ID / Klaviyo, Shopify, or Ometria
email, organization	Customer email, owning org
order_value, currency_code, discount	Transaction data
attributed_campaign	Links to campaign (set during attribution)
json	Raw provider payload (includes shipping address for physical address matching)

Sync pipeline

1. Fetch: celery/sync_orders.py pulls orders since last checkpoint (every 5min)
2. Klaviyo: "Placed Order" metric events
3. Shopify: GraphQL queries
4. Ometria: REST API calls
5. Process: attribute_order() matches recipients by email -> physical address -> discount code
6. Store: upsert_order_by_provider_id() -- idempotent by provider ID
7. Checkpoint: update_organization_order_checkpoint() records last synced datetime

Query patterns

• By email: list_orders_from_email(), list_orders_from_email_and_org()
• By campaign: list_campaign_orders(), list_attributed_orders_from_organization()
• By provider: get_order_by_provider_id() (upsert key)
• By org: get_order_count(), get_last_order()

Key files

• Model: core/models/orders.py
• Sync: celery/sync_orders.py
• Shopify conversion: core/integrations/shopify/models.py
• Ometria conversion: core/models/email_providers/ometria.py