Documentation

Requirements

Installation

Via WordPress Admin

• Go to WordPress Admin → Plugins → Add New
• Search for NettoProfit
• Click Install Now, then Activate
• Navigate to NettoProfit → Settings to complete setup

Via ZIP Upload

• Download nettoprofit.zip from your Freemius account
• Go to Plugins → Add New → Upload Plugin
• Upload the ZIP and activate

On first activation, the plugin creates 9 custom database tables and schedules a historical order backfill via Action Scheduler.

Quick Start

Get up and running in 5 minutes:

1. Check your pixels — Go to NettoProfit → Pixel Health. No setup required. Scan runs automatically.
2. Enter COGS — Go to NettoProfit → Product Costs. Enter cost per product, or bulk import via CSV.
3. Connect ad platforms — Go to NettoProfit → Settings → Integrations. Connect Google, Meta, or TikTok Ads.
4. Configure payment fees — Enter your gateway fee percentages in Settings → Payment Fees.
5. View your dashboard — NettoProfit → Dashboard shows real-time P&L with all costs factored in.

Free vs Pro vs Pro+AI

Pixel Health Checker Free

The Pixel Health Checker audits 5 ad platforms in one scan — no configuration required. It crawls your WooCommerce store's key pages and verifies that pixels are firing correctly with the right events and data fields.

Supported Platforms

• Meta Pixel + Conversions API (CAPI)
• Google Tag (GA4 / GTM) + Consent Mode v2
• TikTok Pixel + Events API
• Pinterest Tag
• Snapchat Pixel

Health Score

Each platform receives a 0–100 score and an A–F letter grade. The score is calculated based on: event presence, event coverage across page types, server-side API status, and data quality (EMQ for Meta).

Meta Event Match Quality (EMQ)

EMQ (0–10) measures how well Meta can match pixel events to real users. Target 8.0+. Improve by enabling Advanced Matching and passing email, phone, and address fields via CAPI.

Google Consent Mode v2

Required for all EU/EEA traffic since March 2024. The checker validates all 4 parameters: ad_storage, analytics_storage, ad_user_data, ad_personalization. Missing parameters trigger a CRITICAL issue.

Dashboard & KPIs Pro

The main dashboard displays 8 KPI cards with period selector and visual P&L charts.

KPI Cards

• Revenue — Total order revenue
• Net Profit — Revenue minus all costs
• Orders — Completed order count
• Avg Margin — Average profit margin %
• Ad Spend — Total synchronized spend
• ROAS — Revenue ÷ Ad Spend
• POAS — Net Profit ÷ Ad Spend
• COGS — Total cost of goods sold

Period Selector

Today · Last 7 Days · Last 30 Days · Last Month

Charts

• P&L Waterfall — Revenue → COGS → Shipping → Payment Fees → Ad Spend → Expenses → Net Profit
• Profit Trend Line — Daily time series (Chart.js)
• POAS Horizontal Bar — Color-coded profitability indicator

Campaign Hierarchy Pro

Full Campaign → Ad Set → Ad drill-down with 11 profit metrics at every level across 6 time periods.

Hierarchy Levels

• Campaigns — All active campaigns with POAS color-coding
• Ad Sets — Drill down into ad set performance
• Ads — Individual ad creative with preview image, full metrics

POAS Status Labels

• 🟢 Highly Profitable — POAS ≥ 1.5
• 🟡 Profitable — POAS 1.0–1.5
• 🟠 Break-Even — POAS 0.5–1.0
• 🔴 Losing Money — POAS < 0

COGS Setup Pro

Enter cost per product and variant. NettoProfit deducts COGS from every order automatically.

Manual Entry

Go to NettoProfit → Product Costs. Click the cost field next to any product to edit inline. Press Enter or click away to save via AJAX.

CSV Bulk Import

Prepare a CSV with two columns: SKU and Cost. Upload via the Import button. A confirmation dialog shows affected products before saving.

SKU,Cost
SHIRT-BLK-S,14.00
SHIRT-BLK-M,14.00
MUG-WHITE,6.80
POSTER-A3,3.50

WooCommerce Product Edit Screen

COGS can also be entered directly on the WooCommerce product edit screen — NettoProfit adds a cost field to both simple products and individual variations.

Expense Management Pro

Track recurring and one-time expenses that reduce net profit. Each expense is prorated to a daily_equiv and deducted from orders proportionally.

Expense Types

• Daily / Weekly / Monthly / Yearly / One-time
• Start Date / End Date (for time-limited expenses)
• Active toggle (disable without deleting)

Example: $500/month Klaviyo subscription → daily_equiv = $16.67 → distributed across orders each day.

Alert System Pro

Automated profit-threshold monitoring. AlertEngine::evaluate() runs daily at 08:00 via WP-Cron.

Default Alert Rules

• profit_negative — Net profit below zero
• poas_low — POAS below your threshold
• Ad Kill — POAS < 0.3, spend > $30, active 3+ days → Critical alert
• Ad Pause — POAS < 0.5 → Warning alert
• Frequency Cap — Ad frequency > 4.0 → Fatigue warning

Notification Channels

• WordPress admin notices
• Email via wp_mail()
• Optional Slack webhook

AI Advisor Pro+AI

Natural-language profit intelligence powered by Claude Sonnet via a fly.io backend. All AI features require the Pro+AI tier.

Features

• Today's Insights — Automated P&L analysis with actionable takeaways
• Ask AI — Free-form questions: "Why did profit drop last week?"
• Ad Copy Generator — 3 ad copy variants from a product brief
• Anomaly Explainer — When an alert fires, AI explains root cause + 3 action steps
• Report Narrator — Weekly plain-English P&L summary for email digest

Token Budget

AI usage is tracked per request. View remaining budget in NettoProfit → AI Advisor → Token Usage. Budget resets with each billing cycle.

Google Ads Integration Pro

Syncs ad spend at the ad-group-ad level every 6 hours. Supports Performance Max campaigns (campaign-level only, PERFORMANCE_MAX badge).

→ Full step-by-step setup guide (6 steps, ~15 min)

Meta Ads Integration Pro

Syncs at individual ad level via Meta Marketing API v21. Supports Advantage+ Shopping campaigns.

→ Full step-by-step setup guide (7 steps)

TikTok Ads Integration Pro

Syncs at auction ad level via TikTok Marketing API v1.3. Supports Smart+ campaigns.

→ Full step-by-step setup guide (6 steps)

UTM & Click ID Tracking

NettoProfit automatically captures UTM parameters and platform click IDs when visitors land on your store. Attribution is stored in a 30-day cookie and written to order meta at checkout.

Captured Parameters

• Standard: utm_source, utm_medium, utm_campaign, utm_term, utm_content
• Google: gclid
• Meta: fbclid
• TikTok: ttclid
• Bing/Microsoft: hsa_cam, hsa_grp, hsa_ad

No additional setup required — capture is automatic on all page loads.

REST API Reference

All endpoints are under the nettoprofit/v1 namespace. Authentication requires a valid WordPress nonce or application password with manage_woocommerce capability.

Free Endpoints

GET /wp-json/nettoprofit/v1/dashboard
GET /wp-json/nettoprofit/v1/pixel/run
GET /wp-json/nettoprofit/v1/pixel/results

Pro Endpoints (22 routes)

GET  /wp-json/nettoprofit/v1/campaigns
GET  /wp-json/nettoprofit/v1/campaigns/{id}
GET  /wp-json/nettoprofit/v1/adsets/{id}
GET  /wp-json/nettoprofit/v1/ads/{id}
GET  /wp-json/nettoprofit/v1/products
POST /wp-json/nettoprofit/v1/products/{id}/cogs
GET  /wp-json/nettoprofit/v1/orders
GET  /wp-json/nettoprofit/v1/expenses
POST /wp-json/nettoprofit/v1/expenses
POST /wp-json/nettoprofit/v1/sync/trigger

AI Endpoints (Pro+AI only)

POST /wp-json/nettoprofit/v1/ai/insights
POST /wp-json/nettoprofit/v1/ai/query
POST /wp-json/nettoprofit/v1/ai/ad-copy
POST /wp-json/nettoprofit/v1/ai/explain-alert
GET  /wp-json/nettoprofit/v1/ai/stats
POST /wp-json/nettoprofit/v1/ai/flush-cache

Database Schema

9 custom tables created on plugin activation, prefixed with pp_:

• pp_ad_spend — Synced ad data: campaign/adset/ad hierarchy, daily spend, ROAS/POAS/CPA
• pp_order_profits — Per-order profit breakdown with full cost waterfall
• pp_product_costs — COGS per product and variant
• pp_expenses — Custom recurring/one-time expenses
• pp_sync_log — Ad sync history per provider
• pp_alert_log — Alert history with severity and AI explanation
• pp_pixel_checks — Archived pixel scan results
• pp_ai_interactions — Claude API call log with token/cost tracking
• pp_campaign_meta — User-defined break-even overrides per campaign

All tables are removed on plugin uninstall. Migrations are version-tracked via nettoprofit_db_version option.

Security

• AES-256-CBC encryption — All API keys stored encrypted using AUTH_KEY as seed
• Prepared statements — All DB queries via $wpdb->prepare()
• HMAC-SHA256 — Webhook endpoint authentication
• Nonce verification — All AJAX handlers and REST endpoints
• Capability checks — manage_woocommerce required on all admin routes
• Input sanitization + output escaping — Throughout all user-facing output
• No external CDN dependencies — Chart.js and dompdf are bundled