From 52e7e9e6988e59490998962edc151035eab996e5 Mon Sep 17 00:00:00 2001
From: Tim Carr <tim@n7studios.co.uk>
Date: Mon, 13 Jul 2026 15:35:28 +0800
Subject: [PATCH] Filter Subscribers: Add `include` parameter support

---
 src/ConvertKit_API_Traits.php |  3 +++
 tests/ConvertKitAPITest.php   | 38 +++++++++++++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/src/ConvertKit_API_Traits.php b/src/ConvertKit_API_Traits.php
index 80a1707..cad34dd 100644
--- a/src/ConvertKit_API_Traits.php
+++ b/src/ConvertKit_API_Traits.php
@@ -1576,6 +1576,7 @@ public function create_subscribers(array $subscribers, string $callback_url = ''
      * @param string                           $counting_mode       Controls how engagement-filter count thresholds are tallied.
      *                                                              - 'raw' (default) counts every event — five opens of the same email = five.
      *                                                              - 'unique_email' counts distinct emails on which the action occurred.
+     * @param array<int, array<string, mixed>> $include             Array of additional fields to embed on each subscriber row.
      * @param boolean                          $include_total_count To include the total count of records in the response, use true.
      * @param string                           $after_cursor        Return results after the given pagination cursor.
      * @param string                           $before_cursor       Return results before the given pagination cursor.
@@ -1590,6 +1591,7 @@ public function create_subscribers(array $subscribers, string $callback_url = ''
     public function filter_subscribers(
         array $all = [],
         string $counting_mode = 'raw',
+        array $include = [],
         bool $include_total_count = false,
         string $after_cursor = '',
         string $before_cursor = '',
@@ -1637,6 +1639,7 @@ public function filter_subscribers(
                 [
                     'all'           => $options,
                     'counting_mode' => $counting_mode,
+                    'include'       => $include,
                 ],
                 $include_total_count,
                 $after_cursor,
diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php
index a2d2ba0..fc136da 100644
--- a/tests/ConvertKitAPITest.php
+++ b/tests/ConvertKitAPITest.php
@@ -4601,6 +4601,44 @@ public function testFilterSubscribersWithCountingMode()
         $this->assertPaginationExists($result);
     }
 
+    /**
+     * Test that filter_subscribers() returns the expected data
+     * when the `include` parameter is specified.
+     *
+     * @since   2.6.0
+     *
+     * @return void
+     */
+    public function testFilterSubscribersWithInclude()
+    {
+        $result = $this->api->filter_subscribers(
+            all: [
+                [
+                    'type' => 'opens',
+                    'count_greater_than' => 0,
+                    'count_less_than' => 100,
+                    'after' => new \DateTime('2024-01-01'),
+                    'before' => new \DateTime('2029-01-01'),
+                    'states' => [
+                        'active',
+                    ],
+                ]
+            ],
+            include: [
+                [
+                    'type' => 'tags',
+                ],
+            ]
+        );
+
+        // Assert subscribers and pagination exist.
+        $this->assertDataExists($result, 'subscribers');
+        $this->assertPaginationExists($result);
+
+        // Assert tags are included.
+        $this->assertArrayHasKey('tags', get_object_vars($result->subscribers[0]));
+    }
+
     /**
      * Test that filter_subscribers() returns the expected data
      * when no parameters are specified.