Route

GET /wp-json/extrachill/v1/analytics/link-page

Purpose

Returns aggregated performance metrics for a single artist link page so roster members can review traffic without leaving the editor experience.

Request Params

Permission Model

• Endpoint requires an authenticated request (cookie-auth or application password).
• ec_can_manage_artist( current_user, artist_id ) must return true; otherwise the response is 403 permission_denied.
• The handler resolves the owning artist ID via apply_filters( 'ec_get_artist_id', $link_page_id ) before capability checks.

Response Contract

When analytics data is available, the endpoint returns whatever payload the extrachill_get_link_page_analytics filter supplies.

The current provider (artist platform) returns an object with:

• summary.total_views and summary.total_clicks
• chart_data.labels and chart_data.datasets (views + clicks series)
• top_links[] entries with text, identifier (URL), and clicks

{
  "summary": { "total_views": 1240, "total_clicks": 312 },
  "chart_data": {
    "labels": ["2026-01-01", "2026-01-02"],
    "datasets": [
      { "label": "Page Views", "data": [120, 98] },
      { "label": "Link Clicks", "data": [32, 21] }
    ]
  },
  "top_links": [
    { "text": "Listen on Spotify", "identifier": "https://open.spotify.com/...", "clicks": 140 }
  ]
}

If no data provider responds or a handler returns WP_Error, the request fails with either 500 analytics_unavailable or the bubbled error from the filter.

Processing Flow

1. Validates args through REST schema and verifies the post represents an artist link page.
2. Resolves the associated artist ID so permission checks are tied to roster ownership.
3. Requires a managing user via ec_can_manage_artist before exposing analytics.
4. Calls apply_filters( 'extrachill_get_link_page_analytics', null, $link_page_id, $date_range ) to fetch data from the analytics provider (usually the artist platform plugin).
5. Returns the filter result verbatim on success.

Error Conditions

Consumer Notes

• Only authenticated roster managers can fetch analytics; anonymous dashboards must proxy through a secure backend.
• Use native REST auth (nonce or application password) when calling from the WordPress admin or block editor.
• Because the payload is fully provider-driven, be prepared to handle additional metrics or nested objects introduced by the analytics plugin.