[Simple Analytics] Subscriber Change Over Time Chart & Mailchimp API Integration

[iamdharmesh]

Description

Build a diverging bar chart showing new subscribers (positive, blue) and unsubscribes (negative, red) over time using the Mailchimp Activity API, with period totals and graceful 180-day limitation handling.

Technical Context:

• Mailchimp API lists/{list_id}/activity returns up to 180 days with subs and unsubs fields
• For ranges beyond 180 days, show informational message and display available data
• Same aggregation interval rules as Form Performance chart
• API errors must not break the rest of the analytics page

Implementation Breakdown

1. REST API/AJAX Endpoint

• GET /mailchimp/v1/analytics/subscriber-activity:
  • Params: list_id, date_from, date_to; Permission: manage_options
  • Fetch from Mailchimp API lists/{list_id}/activity, cache in transient (~15min)
  • Filter to requested date range, aggregate by interval according to the date range
  • Return: { data: [{ label, new_subscribers, unsubscribes }], total_new, total_unsubs, net_change, limited: bool }
  • Set limited: true if date range > 180 days

2. Diverging Bar Chart

• Chart.js bar chart with positive (blue) and negative (red) bars
• Tooltip: New Subscribers, Unsubscribes per bar
• "Totals for the selected date range" summary: Net change (e.g., "+47"), New Subscribers, Unsubscribes

3. API Error & Limitation Handling

• If limited: true, show info notice about 180-day limit
• If Mailchimp API fails, show error message in chart section only (other sections unaffected)
• Loading state while fetching API data

4. Error & Empty States

• No data: charts show "No data available for the selected date range" (copy to be reviewed before final approval)
• API unavailable: Subscriber chart shows error (copy to be reviewed before final approval); other sections unaffected
• No connected forms: Message with link to Form Settings
• Loading states: Skeleton/spinner per section; sections load independently

Acceptance Criteria

• Diverging bar chart shows new subscribers (blue, positive) and unsubscribes (red, negative)
• Data sourced from Mailchimp Activity API, aggregated by correct interval according to the date range
• Tooltips show both metrics per bar
• Period totals (net change, new, unsubs) display correctly
• Ranges > 180 days show informational message with available data
• API failures show error in chart section without breaking KPIs or Form Performance chart
• API responses are cached to reduce Mailchimp API calls
• Chart updates on filter change