Simple Agility Attribution RFC: Marketing Attribution & Sales Flywheel

Status: Draft Architectural RFC (SA-12) · Binds: Roller, Stockroom, JakeMon, simple-agility-accounting · Primary Hub: SimpleAgilityStackHub

This Request for Comments (RFC) establishes the architectural specification for cross-repository marketing attribution across the Simple Agility ecosystem. It defines how customer engagement on the sovereign blogging platform (RollerHub) is measured, correlated, and attributed to physical inventory transactions and revenue realized in the warehouse management system (StockroomIntakeInventoryPricingDesign) and settled in the general ledger (SimpleAgilityCommerceDataFlow).

1. The Multi-Channel Reselling Attribution Dilemma

In modern digital commerce, attribution is typically trivialized by uniform software stacks: an e-commerce storefront (e.g., Shopify, WooCommerce) injects Urchin Tracking Module (UTM) query parameters from an inbound landing page directly into a persistent visitor session cookie. When the customer submits a payment, the shopping cart writes those parameters (utm_source, utm_medium, utm_campaign) into the order record, which is emitted via webhook to the data warehouse.

The Simple Agility small-business architecture faces a fundamentally different structural challenge:

sequenceDiagram
    autonumber
    actor Reader as Customer / Collector
    participant Blog as Roller Fork (docker2)
    participant Umami as Umami Analytics (docker2)
    participant Mkt as Third-Party Channel (eBay / FBA)
    participant SR as Stockroom WMS (docker1)
    participant GL as Accounting Engine (GL)
    participant Dash as JakeMon Grafana (inference)

    Reader->>Blog: Visits spotlight post (/entry/vintage-leica-m3)
    Blog->>Umami: Records pageview (session_id, url_path)
    Reader->>Blog: Clicks [cta] "View Listing on eBay"
    Blog->>Umami: Emits cta-click (entry_anchor, dest=ebay.com)
    Blog-->>Mkt: Redirects to external listing (strips/ignores 3rd-party UTMs)
    Note over Reader,Mkt: Customer purchases item on eBay checkout
    Mkt->>SR: Ingests order via sell.fulfillment (SKU, price, line_id#59; NO UTMs!)
    SR->>GL: Emits ItemSold event (lacks marketing attribution)
    Note over Dash: Blind Spot: Umami sees clicks#59; Stockroom sees sales#59; No join key!

The Marketplace Walled Garden Invariant

1. Third-Party Sanitization: External marketplaces such as eBay, Amazon, Mercari, and Poshmark act as strict walled gardens. When an external outbound link lands on ebay.com/itm/1234567890?utm_source=roller&utm_campaign=leica-m3, eBay’s checkout pipeline intentionally discards third-party UTM parameters.
2. API Data Truncation: When Stockroom's background polling daemon queries eBay's sell.fulfillment REST API (GET /sell/fulfillment/v1/order), the returned JSON payload contains shipping fulfillment lines, buyer delivery addresses, SKU custom labels, and transaction amounts. It provides zero visibility into HTTP referrers, entry URLs, or external campaign identifiers.
3. Local Classified Disconnect: Channels like Craigslist and Facebook Marketplace involve physical handshakes or direct messaging with no automated digital checkout pipeline whatsoever.

Without explicit architectural mechanisms, the ecosystem suffers from an attribution blind spot: Umami measures top-of-funnel reader interest and outbound click-throughs, while Stockroom measures bottom-of-funnel sales and gross margins, but neither product can programmatically verify whether the blog spotlight actually generated the sale.

2. Architectural Survey of Existing Stack Capabilities

The Simple Agility stack already possesses several key architectural primitives that make closed-loop attribution feasible without building heavy third-party tracking services:

flowchart TD
    subgraph Roller_Current["Roller Sovereign Platform"]
        CTA["CtaShortcode.java<br/>[cta] Tagging"]
        BOOK["BookingLink.java<br/>withUtmParams()"]
        FORM["roller_form_submission<br/>(entry_anchor, client_ip)"]
        REV["roller_event<br/>(FORM_SUBMITTED)"]
        CTA --> BOOK
        FORM --> REV
    end

    subgraph Telemetry_Current["Observability & Analytics"]
        UMAMI_DB[("Umami Postgres<br/>website_event")]
        VIEW["analytics_traffic View<br/>(path, entry_anchor, views)"]
        LOKI[("Loki Central Logs<br/>(ECS JsonTemplateLayout)")]
        UMAMI_DB --> VIEW
    end

    subgraph Stockroom_Current["Stockroom Inventory & WMS"]
        CL["channel_listing Table<br/>(item_id, external_id, url)"]
        SALE["sale Table<br/>(item_id, channel, price_cents)"]
        SYNC["EbaySellerAccount Port<br/>sell.fulfillment Poller"]
        CL --> SALE
        SYNC --> SALE
    end

    BOOK -.->|Appends UTMs & data-umami-event| UMAMI_DB
    SALE -.->|Emits ItemSold| LOKI

Component Inventory & Capabilities

• Roller (CtaShortcode.java & BookingLink.java):
  • Automatically injects utm_source=<weblog_handle>, utm_medium=blog, and utm_campaign=<entry_anchor> to all outbound anchor tags.
  • Injects declarative HTML5 data attributes: data-umami-event="cta-click", data-umami-event-entry="<entry_anchor>", and data-umami-event-dest="<dest_host>".
  • Provides native attribution for reader inquiries via roller_form_submission which records the originating entry_anchor in the database.
• Umami Analytics (deploy/analytics/umami-views.sql):
  • Privacy-preserving, cookie-free reader telemetry capturing pageviews (event_type = 1) and custom interactions (event_type = 2).
  • Deployed with a dedicated read-only role (grafana_ro) and the analytics_traffic SQL view grouping daily sessions and views by entry_anchor.
• Stockroom (V022__create_channel_listing.sql, V023__create_sale.sql):
  • Maintains physical item identity via internal UUID and human-readable alphanumeric SKUs (e.g., 1A2B3).
  • Ingests eBay orders by polling sell.fulfillment and matching the SKU present in eBay's Custom label field.
  • Architectural Gap: The sale table possesses no fields for marketing attribution, referral campaigns, coupon codes, or inbound click IDs.

3. The Four Concrete Attribution Vectors

To bridge the gap between Roller content and multi-channel inventory realization, this RFC defines four distinct attribution vectors:

flowchart LR
    subgraph Vectors["Attribution Strategy Matrix"]
        V1["Vector 1: EPN Network<br/>customid=blog_slug_sku"]
        V2["Vector 2: Coded Coupon<br/>order.appliedPromotions"]
        V3["Vector 3: Sovereign Form<br/>roller_form_submission"]
        V4["Vector 4: Single-SKU Heuristic<br/>cta-click timestamp ~ sale"]
    end

    subgraph Targets["Target Channel"]
        EBAY["eBay Marketplace"]
        DIR["Direct Sovereign Sale"]
        LOCAL["Craigslist / Facebook"]
    end

    V1 --> EBAY
    V2 --> EBAY
    V3 --> DIR
    V4 --> EBAY
    V4 --> LOCAL

Vector 1: eBay Partner Network (EPN) Parameterization

eBay operates the eBay Partner Network (EPN), allowing publishers to generate tracked outbound URLs. EPN accepts a custom tracking parameter (customid) that persists through eBay's cart session:

https://www.ebay.com/itm/1234567890?mkcid=1&mkrid=711-53200-19255-0&siteid=0&campid=5339000000&customid=roller_vintagefinds_rolleiflex-28f_1A2B3

• Payload Structure: roller_<weblog_handle>_<entry_anchor>_<sku> (limited to 256 alphanumeric and underscore characters).
• Reporting: EPN provides a daily Transaction Detail Report (downloadable via REST API or CSV) detailing every qualified sale, item title, transaction amount, and the exact customid that triggered it.
• Economics: Rather than costing money, EPN pays the publisher an affiliate commission (or fee rebate), effectively offsetting standard eBay selling fees.

Vector 2: Marketplace Coded Coupons

For sellers holding an eBay Store subscription, eBay supports Coded Coupons (public or private alphanumeric voucher codes, e.g., ROLLER5 or SPOTLIGHT10):

1. The publisher agent (blogger-agent) embeds an exclusive promotional callout into the Roller entry body:

   Readers of Simple Agility can take an additional 5% off this camera at eBay checkout using code ROLLER5.

2. When the buyer enters the code during eBay checkout, eBay validates and attaches the promotion to the order record.
3. In eBay's sell.fulfillment API (GET /sell/fulfillment/v1/order/{orderId}), the order payload includes:

   {
     "orderId": "12-34567-89012",
     "pricingSummary": {
       "priceDiscount": {
         "value": "15.00",
         "currency": "USD"
       }
     },
     "appliedPromotions": [
       {
         "promotionId": "promo-987654",
         "description": "ROLLER5"
       }
     ]
   }
   

4. Stockroom’s order sync extracts description and writes it to the sale record, establishing unambiguous attribution.

Vector 3: Sovereign Direct Checkout & Inquiry Forms

The highest-margin transaction occurs when an item is sold directly to a reader, circumventing marketplace commission fees.

• Contact Inquiry Flow: Roller's native roller_form_submission captures customer purchase inquiries, recording the entry_anchor directly. The operator invoices the customer directly (via ACH, check, or Stripe invoice) and records the sale in Stockroom as channel in_person or direct.
• Stripe Payment Links: For fixed-price spotlight items, the agent can generate a Stripe Payment Link with embedded client metadata:

  https://buy.stripe.com/test_123456?client_reference_id=roller_estate_rolleiflex_1A2B3
  

  Stripe's checkout.session.completed webhook delivers the exact client_reference_id to simple-agility-accounting.

Vector 4: Deterministic Single-Quantity SKU Temporal Heuristic

Because the reselling business manages unique, non-fungible inventory (e.g., a specific used book, an estate camera, a vintage precision tool), the inventory differs radically from bulk retail:

• Each item has quantity = 1.
• Each item is bound to a unique Stockroom alphanumeric SKU (e.g., 1A2B3) published in eBay's Custom label.
• If Roller publishes an article featuring SKU 1A2B3, and Umami registers an outbound cta-click for that specific entry anchor, and Stockroom records a sale for SKU 1A2B3 within a configurable conversion window (within 48 hours):
• The probability of a false positive (a random buyer discovering and purchasing that specific unique item on eBay within 48 hours without having read the blog) is inversely proportional to the item's baseline organic search velocity. For slow-moving, high-margin collectibles, this heuristic achieves 98%+ practical accuracy without requiring third-party affiliate tokens.

4. Proposed Database Schema and Event Extensions

To support attribution vectors 2, 3, and 4, the following data model extensions are proposed for future suite phases:

Stockroom Schema Migration (V028__add_attribution_to_sale.sql)

-- Migration: V028__add_attribution_to_sale.sql
-- Module: stockroom-persistence
-- Purpose: Support marketing attribution from Roller blog spotlights and promo codes

ALTER TABLE sale
    ADD COLUMN attribution_channel varchar(32),
    ADD COLUMN attribution_campaign varchar(255),
    ADD COLUMN promo_code varchar(64),
    ADD COLUMN attribution_confidence numeric(3,2);

COMMENT ON COLUMN sale.attribution_channel IS 'Source of marketing lead: roller_blog, newsletter, direct_inquiry, or null';
COMMENT ON COLUMN sale.attribution_campaign IS 'Originating blog entry_anchor or newsletter campaign ID';
COMMENT ON COLUMN sale.promo_code IS 'Marketplace coupon or voucher code applied at checkout';
COMMENT ON COLUMN sale.attribution_confidence IS 'Attribution confidence score between 0.00 and 1.00 (1.00 = coupon/direct form; 0.90 = single-SKU temporal)';

CREATE INDEX idx_sale_attribution ON sale (attribution_channel, attribution_campaign)
    WHERE attribution_channel IS NOT NULL;

Accounting Event Schema Extension (ItemSold)

In accordance with SimpleAgilityCommerceDataFlow, the immutable ItemSold event payload is expanded to carry optional attribution metadata:

{
  "event_id": "evt_01JAZ9876543210ABCDEFGHJK",
  "event_type": "ItemSold",
  "occurred_at": "2026-10-17T14:32:00Z",
  "actor": "system:ebay_sync",
  "data": {
    "item_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "sku": "1A2B3",
    "channel": "ebay",
    "gross_proceeds_cents": 30000,
    "channel_fees_cents": 4015,
    "net_cents": 25985,
    "attribution": {
      "channel": "roller_blog",
      "campaign": "vintage-rolleiflex-28f-review",
      "promo_code": "ROLLER5",
      "confidence": 1.00
    }
  }
}

5. Mathematical Modeling of Attribution Economics

Attribution telemetry is not merely an operational dashboard; it governs the allocation of marketing effort and channel selection.

1. Return on Content Investment (ROCI)

The financial justification for authoring deep-dive inventory spotlights is governed by the net profit generated above baseline content authoring costs:

Where:

• NetProceeds: Realized gross sale price minus marketplace fees and postage.
• COGS: Inbound acquisition cost allocated from the intake lot (SimpleAgilityCommerceDataFlow).
• Content Costs: Operator photography time and LLM inference token costs incurred staging the spotlight draft via /api/mcp.

2. Marketplace Arbitrage Margin Delta

When an attribution vector successfully steers a customer from an external marketplace to a direct sovereign transaction (Vector 3), the margin expansion is calculated as:

Concrete Numerical Example: Rare Estate Camera

Consider a rare estate camera priced at $300.00:

eBay Marketplace Sale (Vector 1 or 2):

• Gross Proceeds: $300.00
• eBay Final Value Fee (13.25% + $0.40): $300.00 * 0.1325 + $0.40 = $39.75 + $0.40 = $40.15
• Net Realized to Business: $300.00 - $40.15 = $259.85

Direct Sovereign Sale via Roller Inquiry / Stripe (Vector 3):

• Gross Proceeds: $300.00
• Stripe Processing Fee (2.9% + $0.30): $300.00 * 0.029 + $0.30 = $8.70 + $0.30 = $9.00
• Net Realized to Business: $300.00 - $9.00 = $291.00

Arbitrage Benefit:

A direct transaction via the Roller blog preserves an additional $31.15 (10.38% of gross sale price) directly to the bottom line.

6. Implementation Phasing and Handoff Plan

To preserve development momentum while keeping systems strictly bounded, implementation of this RFC is phased across suite roadmaps:

flowchart TD
    P1["Phase 1: Zero-Code Observability (Immediate)"]
    P2["Phase 2: EPN & Coupon Operationalization (Near-Term)"]
    P3["Phase 3: Schema & Poller Integration (Future Suite Phase)"]

    P1 -->|Deploy Umami/Stockroom Grafana View| P2
    P2 -->|Blogger Agent generates EPN & Coupons| P3
    P3 -->|Stockroom V028 Migration & GL Ingestion| DONE["Closed-Loop Attribution Engine"]

Phase 1: Zero-Code Observability (No Code Changes)

• Mechanism: Vector 4 (Single-SKU Temporal Correlation).
• Execution: Add a cross-database dashboard in JakeMon Grafana querying umami.website_event and stockroom.sale. By plotting cta-click timestamps against eBay sale timestamps for featured SKUs, the operator gains immediate directional visibility into blog-assisted conversions without modifying any production application code.

Phase 2: EPN & Coded Coupon Operationalization

• Mechanism: Vectors 1 and 2.
• Execution:
  1. Operator registers an EPN publisher account and obtains a Campaign ID (campid).
  2. The publishing agent (blogger-agent / RollerMcp) is instructed to construct outbound links containing EPN tracking parameters and promo codes.
  3. Coded coupons (e.g., ROLLER5) are configured in eBay Seller Hub.

Phase 3: Automated Stockroom & Ledger Integration

• Mechanism: Full programmatic ingestion.
• Execution:
  1. Stockroom Core Engineering Agent applies Flyway migration V028__add_attribution_to_sale.sql.
  2. EbayOrderLineMapper in stockroom-channels is updated to parse appliedPromotions and write the coupon code to sale.promo_code.
  3. ItemSold event payloads propagate attribution metadata to simple-agility-accounting.

See Also

• SimpleAgilityStackHub — Small-business ecosystem architecture and shared data backbone.
• SimpleAgilityDecisionLog — Binding architectural decisions including SA-8 (spotlights) and SA-12 (attribution).
• RollerHub — Customer communication engine, Umami analytics views, and agent publishing.
• ResellingHub — Business rules, condition grading, and spotlight selection policies.
• SimpleAgilityCommerceDataFlow — Complete transaction lifecycle, double-entry ledger mappings, and event schemas.
• SimpleAgilityTelemetryContract — Logging standards, trace propagation, and ECS formatting.