Sales Performance Analysis

Sales Performance Analysis

Produces a same-period MoM sales comparison across four data streams: gross invoicing, credit notes, sales by item, and sales by plan. Both windows span the same number of days so the comparison is like-for-like.

Step 0 — Setup

Org ID: Retrieve via list_organizations if not already known. Ask if multiple orgs exist — never guess.

Date windows — compute as follows, then confirm with the user before proceeding:

today         = current date
cm_start      = first day of the current calendar month
cm_end        = today

lm_start      = first day of the prior calendar month
lm_end        = prior month's day number matching today's day
              → if today is May 19, lm_end = April 19
              → if today is May 31 but April has only 30 days, lm_end = April 30

period_label_cm = "<Month> 1–<today_day>" (e.g. "May 1–19")
period_label_lm = "<Prior Month> 1–<today_day>" (e.g. "April 1–19")

State the windows in one line and offer to use custom dates:

"Comparing May 1–19 vs April 1–19. Want to use different dates instead?"

If the user provides custom dates, use those for both windows. Ensure both windows span the same number of days for a fair comparison; warn if they differ.

Step 1 — Fetch all data (8 calls in parallel)

Run all 8 calls in a single turn — they are fully independent.

Paginate while has_more_page: true. Cap invoice details at 5 pages (500 invoices) per period; note if cap is hit. Use API-level total fields for period sums — do not sum rows (undercounts when pagination truncates).

Step 2 — Compute revenue metrics

2a. Gross invoicing & credit notes

CP = current period, PP = prior period

2b. Invoice count and average deal size

• Invoice count CP and PP
• Average invoice value CP = gross_CP / invoice_count_CP
• Average invoice value PP = gross_PP / invoice_count_PP
• MoM average deal size Δ (absolute and %)

2c. Top items

From calls #5 and #6, rank items by total descending. Take top 10 by CP revenue.

For each item: item name, quantity sold, total revenue, % of CP gross invoiced.

Build a side-by-side comparison: for each top-10 CP item, look it up in PP data. Call out items that:

• Are new in CP (no PP revenue) — emerging products
• Dropped out of top 10 from PP — declining products
• Had the biggest absolute revenue swing (up or down)

Also compute: top-item concentration = (item_1_total / gross_CP) × 100. A single item driving > 60% of revenue is a diversification risk worth naming.

2d. Top plans

Same analysis as 2c but using calls #7/#8. Top 10 plans by CP revenue. For each plan: plan name, total revenue CP and PP, MoM delta.

Step 3 — Credit note breakdown

From calls #3/#4:

• Total credit note count CP vs. PP
• Average credit note value
• If reason/description is available → top 3 reasons by count
• Any single customer accounting for > 20% of CP credit notes (concentration risk)

Step 4 — Invoice health (current period only)

From call #1, flag if present:

• Overdue invoices: status: overdue — count and total value
• Draft invoices: not yet sent — count
• Flag if overdue value > 10% of gross_CP (worth surfacing, not a failure)

Step 5 — Produce the analysis output

Write a clean Markdown section (no green/amber/red scoring — let the numbers speak):

## Sales Performance — <period_label_cm> vs <period_label_lm>

### Revenue Summary
| Metric | <period_label_lm> | <period_label_cm> | Δ |
|---|---|---|---|
| Gross invoiced | $X | $Y | +$Z (+N%) |
| Credit notes | $X | $Y | +$Z |
| Net revenue | $X | $Y | +$Z (+N%) |
| Invoice count | N | N | +N |
| Avg deal size | $X | $Y | +$Z |
| Credit note ratio | N% | N% | +Npp |

**Net revenue: <direction and magnitude in plain English>**

### Top 10 Items
| Rank | Item | PP Revenue | CP Revenue | Δ | Δ% |
|---|---|---|---|---|---|
...
_Top-item concentration: N% of gross from "<item name>"_

### Top 10 Plans
| Rank | Plan | PP Revenue | CP Revenue | Δ | Δ% |
|---|---|---|---|---|---|
...

### Credit Notes
- CP: $X across N notes (N% of gross)
- PP: $Y across M notes (N% of gross)
<top reason or concentration note if data available>

### Invoice Health (Current Period)
- Overdue: N invoices · $X outstanding
- Draft: N invoices pending

Output contract (for orchestrator)

Pass this JSON object back alongside the Markdown section:

{
  "pillar": "revenue",
  "period_label_cm": "May 1–19",
  "period_label_lm": "April 1–19",
  "metrics": {
    "gross_invoiced_cp": <number>,
    "gross_invoiced_pp": <number>,
    "mom_gross_pct": <number>,
    "credit_notes_cp": <number>,
    "credit_note_ratio_cp_pct": <number>,
    "net_revenue_cp": <number>,
    "net_revenue_pp": <number>,
    "mom_net_revenue_pct": <number>,
    "invoice_count_cp": <number>,
    "avg_deal_size_cp": <number>,
    "top_item_concentration_pct": <number>
  },
  "top_items": [{"name": "...", "revenue_cp": ..., "revenue_pp": ..., "delta_pct": ...}],
  "top_plans": [{"name": "...", "revenue_cp": ..., "revenue_pp": ..., "delta_pct": ...}],
  "flags": ["<overdue > 10%>", "<credit note concentration>"]
}

Edge cases

• Day 1 of month: CP has only today's data. Note "Day 1 — only available." Use LM same-day (e.g. April 1 only) — both are single-day windows, still comparable.
• Zero invoices in either period: state explicitly; don't infer.
• Multi-currency org: use base-currency total field; note mixed-currency if relevant.
• Pagination cap: note "invoice totals from API summary field — accurate regardless of pagination cap."
• No credit notes: skip credit note section; set ratio = 0.
• Prior month shorter than current (e.g. Feb when today is March 29): lm_end = Feb 28/29. Note the truncation once.