04: CAPI Edge Gateway Event Integrity and Revenue Reconciliation
Treat a conversion as a traceable business event before treating it as an advertising signal.
1. Objective and Ownership
Duplicate purchases, incorrect currency, and missing consent can corrupt optimization while dashboards continue to show activity. Server-side delivery needs an explicit event contract and independent reconciliation.
The Measurement Lead owns event semantics. Engineering owns delivery. Finance owns the revenue definition. The privacy owner approves destination-specific eligibility rules.
The proposed NoLimit Shopping Proprietary Engine includes a CAPI Edge Gateway for validation and delivery. This is a reference design, not a claim that NoLimit currently offers a deployed gateway.
2. Prerequisites and Event Contract
| Field | Contract |
|---|---|
| Tenant and destination | Authorized client and exact event source |
| Event name | Approved business action with consistent meaning |
| Event ID | Stable opaque identifier for one logical event |
| Event time | Actual occurrence time in the required format |
| Value and currency | Finance-approved calculation and currency |
| Processing eligibility | Purpose, jurisdiction, preference state, and policy version |
| Customer identifiers | Only permitted fields, normalized as the destination requires |
| Schema version | Versioned mapping and release owner |
Define when a purchase occurs: authorization, capture, or another documented business milestone. A browser page refresh must not create another purchase. Hashing personal data does not remove the need for appropriate processing controls.
3. Execution Procedure
- **Create the event at the business source.** Generate a stable event ID when the defined purchase milestone occurs. Make it available to both browser and server implementations when both report that event.
- **Authenticate ingestion.** Validate source signatures where available, enforce tenant scope, and apply replay controls appropriate to the integration.
- **Evaluate eligibility.** Apply the approved destination policy before export. Missing required permission means hold or suppress, not assume consent. Re-evaluate queued events before replay after preference changes.
- **Validate payloads.** Reject impossible timestamps, unknown currencies, missing required fields, and destination mismatches. Minimize diagnostic data.
- **Persist before dispatch.** Use a durable outbox or equivalent recovery mechanism linked to the source transaction. Avoid an unprotected database-write-plus-network-call sequence.
- **Deduplicate at two layers.** Prevent repeated internal jobs with a unique key such as tenant, destination, event name, and event ID. For corresponding browser and server events, preserve the matching event identifiers and names required by the destination.
- **Retry selectively.** Retry transient failures with bounded exponential backoff and jitter. Preserve original event identity and occurrence time. Quarantine permanent validation failures; honor current destination age and rate limits.
- **Reconcile delivery.** Distinguish queued, accepted by the destination, rejected, and suppressed events. Acceptance is not proof of attribution.
4. Validation and Release Gates
Test duplicate delivery, browser refresh, queue restart, destination timeout, revoked permission, multiple currencies, and a cancelled order.
For an isolated test cohort of 1,000 eligible purchase events, suppose 990 are accepted, six permanently rejected, and four queued. Delivery completeness is 99%; all 1,000 must remain accounted for. Do not compare that figure directly with platform-attributed purchases.
Release requires correct event identity, tenant routing, eligibility enforcement, and reconciliation. Set an internal freshness objective separately from destination acceptance limits. For example, p95 dispatch within 60 seconds may be an engineering target, not an attribution guarantee.
5. Incident Response and Rollback
Disable the faulty mapping or destination export while preserving eligible events within approved retention limits. Never repair duplication by replaying purchases with new IDs.
Restore the last validated mapping, replay only eligible recoverable events, and reconcile the incident cohort. A refund is a separate business event or supported adjustment; do not assume a negative purchase is accepted by every destination.
6. KPIs and Operating Cadence
Monitor eligible-event delivery completeness, duplicate attempts, schema rejection rate, queue age, reconciliation variance, and prohibited exports. Record numerator, denominator, cohort, and reporting window for every metric.
Compare finance revenue and measurement events daily using aligned definitions. Keep attributed revenue separate from total revenue and incrementality. The output is a versioned event contract, test evidence, and a reconciled delivery report.
---
