Subscribers Page: Create API endpoint returning subscribers' data

[ivan-ottinger]

Create API endpoint (or extend existing one if possible and worth it) that will provide all necessary information about subscribers (email subscribers, notification subscribers, paid subscribers, WPCOM and external users).

Data required:

• total (number)
• page (number)
• pages (number)
• subscribers (array of subscriber objects that will have the values listed below)
  • user_id (number)
  • subscription_id (number) - potential confusion with paid_subscription_id of paid subscription
  • username (string)
  • email_address (string)
  • display_name (string) (probably Display name will be better than First / Last name) (string)
  • avatar (string - image URL) Gravatar / user's profile picture
  • date_subscribed (string) example format 2023-05-25T08:19:30+00:00 (including the timezone - format used by the "followers" endpoint) or 2023-06-26 09:52:23 (without the timezone specified and in UTC - format used by the "memberships" endpoint) - date of when the user subscribed
  • plans (array of plan objects that will have the values listed below)
  • paid_subscription_id (number)
  • status (string)
  • title (string)
  • currency (string)
  • start_date (string)
  • end_date (string)

As for the plan object, we may consider including all values that are currently outputted by the "memberships" endpoint (please see below).

Existing APIs that might be helpful:

https://public-api.wordpress.com/rest/v1.1/sites/[site-id]/followers?http_envelope=1&max=100&type=all&page=1 used at https://wordpress.com/people/subscribers/[site-address] (People → Subscribers) page

Example output:

{
    "code": 200,
    "headers": [
        {
            "name": "Content-Type",
            "value": "application/json"
        }
    ],
    "body": {
        "page": 1,
        "pages": 1,
        "total": 22,
        "total_email": 18,
        "total_wpcom": 4,
        "subscribers": [
            {
                "avatar": "https://2.gravatar.com/avatar/bda1305b6bfbb6862820888fd34ae6f5?s=64&d=https%3A%2F%2F2.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D64&r=G",
                "label": "tester-external@example.com",
                "ID": "434234234",
                "url": null,
                "follow_data": null,
                "date_subscribed": "2023-05-25T15:34:36+00:00"
            },
            {
                "avatar": "https://2.gravatar.com/avatar/28cf9b1dfd22e9e564daef25397934cd?s=64&d=https%3A%2F%2F2.gravatar.com%2Favatar%2Fad516503a11cd5ca435acc9bb6523536%3Fs%3D64&r=G",
                "label": "wpcomusername",
                "login": "wpcomusername",
                "ID": 423422298,
                "url": "http://test3192138908299.placeholder.place",
                "follow_data": {
                    "params": {
                        "stat-source": "stats_comments",
                        "follow-text": "Follow",
                        "following-text": "Following",
                        "following-hover-text": "Unfollow",
                        "blog_domain": "test3192138908299.placeholder.place",
                        "blog_url": "http://test3192138908299.placeholder.place",
                        "blog_id": 9870980,
                        "site_id": 9870980,
                        "blog_title": "Test",
                        "is_following": true
                    },
                    "type": "follow"
                },
                "date_subscribed": "2022-09-30T12:39:16+00:00"
            },
        ]
    }
}

---

https://public-api.wordpress.com/wpcom/v2/sites/[site-id]/memberships/subscribers?offset=0&_envelope=1 used at https://wordpress.com/earn/payments/[site-address] (Tools → Earn → Manage Premium Content) page

Example output:

{
    "body": {
        "ownerships": [
            {
                "id": "2342347874",
                "user": {
                    "ID": 8907439234,
                    "user_login": "username-example",
                    "user_email": "useremail@example.com",
                    "name": "user's name",
                    "avatar_URL": "https://secure.gravatar.com/avatar/e31e564af47d11cd8daf7188b3ee3562?s=96&d=identicon&r=g"
                },
                "plan": {
                    "connected_account_product_id": "42343",
                    "connected_destination_account_id": "234234",
                    "product_slug": "memberships",
                    "product_variation_slug": "4343434_2070",
                    "site_id": "4343434",
                    "renew_interval": "1 year",
                    "renewal_price": "3",
                    "title": "Yearly Subscription",
                    "details": "{\"buyer_can_change_amount\":false,\"multiple_per_user\":true,\"subscribe_as_site_subscriber\":false,\"welcome_email_content\":\"\",\"type\":null}",
                    "currency": "USD",
                    "buyer_can_change_amount": false,
                    "multiple_per_user": true,
                    "subscribe_as_site_subscriber": false,
                    "welcome_email_content": "",
                    "type": null
                },
                "start_date": "2023-06-05 09:25:07",
                "end_date": "2024-06-05 09:25:07",
                "renew_interval": "1 year",
                "status": "active",
                "all_time_total": "3.00"
            },
            {
                "id": "43229809",
                "user": {
                    "ID": 984392,
                    "user_login": "username-example",
                    "user_email": "useremail@example.com",
                    "name": "user's name",
                    "avatar_URL": "https://secure.gravatar.com/avatar/e31e564af47d11cd8daf7188b3ee3562?s=96&d=identicon&r=g"
                },
                "plan": {
                    "connected_account_product_id": "42343",
                    "connected_destination_account_id": "234234",
                    "product_slug": "memberships",
                    "product_variation_slug": "4343434_2051",
                    "site_id": "4343434",
                    "renew_interval": "1 month",
                    "renewal_price": "2",
                    "title": "Monthly Subscription Test Plan",
                    "details": "{\"buyer_can_change_amount\":false,\"multiple_per_user\":false,\"subscribe_as_site_subscriber\":true,\"welcome_email_content\":\"\",\"type\":null}",
                    "currency": "EUR",
                    "buyer_can_change_amount": false,
                    "multiple_per_user": false,
                    "subscribe_as_site_subscriber": true,
                    "welcome_email_content": "",
                    "type": null
                },
                "start_date": "2023-05-26 09:52:23",
                "end_date": "2023-06-26 09:52:23",
                "renew_interval": "1 month",
                "status": "active",
                "all_time_total": "2.00"
            }
        ],
        "total": "2"
    },
    "status": 200,
    "headers": {
        "Allow": "GET"
    }
}

[TimBroddin]

I think WPCOM_REST_API_V2_Endpoint_Subscribers would be a good place to add this code. There are already several endpoints defined in that class to get the count and import subscribers, but none to list them.

[simison]

How come you'd not extend existing /sites/[site-id]/followers API which is used to list subscribers currently?

[TimBroddin]

How come you'd not extend existing /sites/[site-id]/followers API which is used to list subscribers currently?

I considered this. But since it's a 1.1 endpoint, and I understood that we'd like new functionality to live in the v2 namespace, I thought that the subscriber endpoint would be better a better place for it to live.

I have a WIP PR ready for this: D112832-code

[TimBroddin]

Closed in D112832-code