feat(stripe): add optional subscription pagination cursors

Author: waleedlatif1

apps/docs/content/docs/integrations/stripe.mdx

@@ -1299,7 +1299,7 @@ Resume a subscription that was scheduled for cancellation
 
 ### Stripe List Subscriptions
 
-List all subscriptions
+List one page of subscriptions. Follow starting_after while metadata.has_more is true.
 
 #### Input
 
@@ -1309,6 +1309,8 @@ List all subscriptions
 | `limit` | number | No | Number of results to return \(default 10, max 100\) |
 | `customer` | string | No | Filter by customer ID |
 | `status` | string | No | Filter by status \(active, past_due, unpaid, canceled, incomplete, incomplete_expired, trialing, all\) |
+| `starting_after` | string | No | Next-page cursor: last subscription ID from the previous page. Do not combine with ending_before. |
+| `ending_before` | string | No | Previous-page cursor: first subscription ID from the current page. Do not combine with starting_after. |
 | `price` | string | No | Filter by price ID |
 
 #### Output
@@ -1378,14 +1380,15 @@ List all subscriptions
 
 ### Stripe Search Subscriptions
 
-Search for subscriptions using query syntax
+Search one page of subscriptions using query syntax. Pass metadata.next_page as page to continue.
 
 #### Input
 
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `apiKey` | string | Yes | Stripe API key \(secret key\) |
 | `query` | string | Yes | Search query \(e.g., "status:'active' AND customer:'cus_xxx'"\) |
+| `page` | string | No | Pagination token from metadata.next_page. Omit for the first page and keep the same query. |
 | `limit` | number | No | Number of results to return \(default 10, max 100\) |
 
 #### Output
@@ -1452,6 +1455,7 @@ Search for subscriptions using query syntax
 | `metadata` | json | Search metadata |
 |   ↳ `count` | number | Number of items returned |
 |   ↳ `has_more` | boolean | Whether more items exist beyond this page |
+|   ↳ `next_page` | string | Token for the next page of search results, or null when there are no more results |
 
 ### Stripe Create Invoice
 

apps/sim/blocks/blocks/stripe.ts

@@ -708,6 +708,30 @@ export const StripeBlock: BlockConfig<StripeResponse> = {
       },
       required: true,
     },
+    {
+      id: 'starting_after',
+      title: 'Starting After',
+      type: 'short-input',
+      placeholder: 'Last subscription ID from the previous page',
+      condition: { field: 'operation', value: 'list_subscriptions' },
+      mode: 'advanced',
+    },
+    {
+      id: 'ending_before',
+      title: 'Ending Before',
+      type: 'short-input',
+      placeholder: 'First subscription ID from the current page',
+      condition: { field: 'operation', value: 'list_subscriptions' },
+      mode: 'advanced',
+    },
+    {
+      id: 'page',
+      title: 'Search Page',
+      type: 'short-input',
+      placeholder: 'Token from metadata.next_page; omit for the first page',
+      condition: { field: 'operation', value: 'search_subscriptions' },
+      mode: 'advanced',
+    },
     // Additional filters for specific list operations
     {
       id: 'status',
@@ -976,6 +1000,9 @@ export const StripeBlock: BlockConfig<StripeResponse> = {
     recurring: { type: 'json', description: 'Recurring billing configuration' },
     // List/Search inputs
     limit: { type: 'number', description: 'Maximum results to return' },
+    starting_after: { type: 'string', description: 'Next-page subscription ID cursor' },
+    ending_before: { type: 'string', description: 'Previous-page subscription ID cursor' },
+    page: { type: 'string', description: 'Subscription search token from metadata.next_page' },
     query: { type: 'string', description: 'Search query' },
     status: { type: 'string', description: 'Status filter' },
     type: { type: 'string', description: 'Event type filter' },

apps/sim/tools/generated/tool-metadata.ts

@@ -75,6 +75,8 @@ import { searchIssuesV2Tool } from '@/tools/github/search_issues'
 import { memoryAddTool } from '@/tools/memory/add'
 import { createInternalToolOperationInput } from '@/tools/operation-input'
 import { slackListsItemsListTool } from '@/tools/slack_lists/items_list'
+import { stripeListSubscriptionsTool } from '@/tools/stripe/list_subscriptions'
+import { stripeSearchSubscriptionsTool } from '@/tools/stripe/search_subscriptions'
 import { getCallerIdentityTool } from '@/tools/sts/get_caller_identity'
 import { tableBatchInsertRowsTool } from '@/tools/table/batch_insert_rows'
 import type { InternalToolConfig, ToolResponse } from '@/tools/types'
@@ -183,6 +185,8 @@ vi.mock('@/executor/handlers/workflow/custom-block-tool-runner', () => ({
 // Mock the tools registry to avoid loading the full 4500+ line registry file.
 // Only the tools actually exercised in tests are provided.
 const mockRegistryTools: Record<string, any> = {
+  stripe_list_subscriptions: stripeListSubscriptionsTool,
+  stripe_search_subscriptions: stripeSearchSubscriptionsTool,
   slack_lists_items_list: slackListsItemsListTool,
   github_search_issues_v2: searchIssuesV2Tool,
   bitbucket_get_pipeline_step_log: bitbucketGetPipelineStepLogTool,
@@ -2862,6 +2866,163 @@ describe('executeTool Function', () => {
   })
 })
 
+describe('Stripe subscription pagination through tool execution', () => {
+  beforeEach(() => {
+    mockValidateUrlWithDNS.mockResolvedValue({ isValid: true, resolvedIP: '93.184.216.34' })
+    mockSecureFetchWithPinnedIP.mockReset()
+  })
+
+  it('retains first-page filters and returns one page even when more subscriptions exist', async () => {
+    mockSecureFetchWithPinnedIP.mockResolvedValueOnce(
+      toSecureFetchResponse(
+        Response.json({
+          object: 'list',
+          data: [{ id: 'sub_first' }, { id: 'sub_last' }],
+          has_more: true,
+        })
+      )
+    )
+
+    const result = await executeTool('stripe_list_subscriptions', {
+      apiKey: 'sk_test_pagination',
+      limit: 100,
+      customer: 'cus_example',
+      status: 'active',
+      price: 'price_example',
+    })
+
+    expect(result).toMatchObject({
+      success: true,
+      output: {
+        subscriptions: [{ id: 'sub_first' }, { id: 'sub_last' }],
+        metadata: { count: 2, has_more: true },
+      },
+    })
+    expect(mockSecureFetchWithPinnedIP).toHaveBeenCalledExactlyOnceWith(
+      'https://api.stripe.com/v1/subscriptions?limit=100&customer=cus_example&status=active&price=price_example',
+      '93.184.216.34',
+      expect.objectContaining({
+        method: 'GET',
+        headers: expect.objectContaining({ authorization: 'Bearer sk_test_pagination' }),
+      })
+    )
+  })
+
+  it.each(['starting_after', 'ending_before'] as const)(
+    'retrieves the requested %s page without interpreting cursor characters as filters',
+    async (direction) => {
+      const cursor = 'sub_cursor&status=canceled'
+      mockSecureFetchWithPinnedIP.mockImplementationOnce(async (url) => {
+        const request = new URL(url)
+        const valid =
+          request.pathname === '/v1/subscriptions' &&
+          request.searchParams.get(direction) === cursor &&
+          request.searchParams.get('status') === 'active'
+        return toSecureFetchResponse(
+          valid
+            ? Response.json({ object: 'list', data: [{ id: 'sub_next' }], has_more: false })
+            : Response.json(
+                { error: { message: 'Unexpected pagination request' } },
+                { status: 400 }
+              )
+        )
+      })
+
+      const result = await executeTool('stripe_list_subscriptions', {
+        apiKey: 'sk_test_pagination',
+        status: 'active',
+        [direction]: cursor,
+      })
+
+      expect(result).toMatchObject({
+        success: true,
+        output: { subscriptions: [{ id: 'sub_next' }], metadata: { count: 1, has_more: false } },
+      })
+      expect(mockSecureFetchWithPinnedIP).toHaveBeenCalledOnce()
+    }
+  )
+
+  it('rejects conflicting list cursors before contacting Stripe', async () => {
+    mockSecureFetchWithPinnedIP.mockResolvedValueOnce(
+      toSecureFetchResponse(Response.json({ object: 'list', data: [], has_more: false }))
+    )
+
+    const result = await executeTool('stripe_list_subscriptions', {
+      apiKey: 'sk_test_pagination',
+      starting_after: 'sub_last',
+      ending_before: 'sub_first',
+    })
+
+    expect(result).toMatchObject({
+      success: false,
+      error: expect.stringContaining('Provide either starting_after or ending_before, not both'),
+    })
+    expect(mockSecureFetchWithPinnedIP).not.toHaveBeenCalled()
+  })
+
+  it('round-trips the search continuation token and exposes the terminal page', async () => {
+    const query = "status:'active'"
+    const nextPage = 'opaque/search+cursor=='
+    mockSecureFetchWithPinnedIP.mockImplementation(async (url) => {
+      const request = new URL(url)
+      if (
+        request.pathname !== '/v1/subscriptions/search' ||
+        request.searchParams.get('query') !== query ||
+        request.searchParams.get('limit') !== '100'
+      ) {
+        return toSecureFetchResponse(
+          Response.json({ error: { message: 'Search filters changed' } }, { status: 400 })
+        )
+      }
+      const page = request.searchParams.get('page')
+      if (page === null) {
+        return toSecureFetchResponse(
+          Response.json({
+            object: 'search_result',
+            data: [{ id: 'sub_first' }],
+            has_more: true,
+            next_page: nextPage,
+          })
+        )
+      }
+      return toSecureFetchResponse(
+        page === nextPage
+          ? Response.json({ object: 'search_result', data: [{ id: 'sub_last' }], has_more: false })
+          : Response.json({ error: { message: 'Invalid search page' } }, { status: 400 })
+      )
+    })
+
+    const first = await executeTool('stripe_search_subscriptions', {
+      apiKey: 'sk_test_pagination',
+      query,
+      limit: 100,
+    })
+    expect(first).toMatchObject({
+      success: true,
+      output: {
+        subscriptions: [{ id: 'sub_first' }],
+        metadata: { count: 1, has_more: true, next_page: nextPage },
+      },
+    })
+    expect(mockSecureFetchWithPinnedIP).toHaveBeenCalledOnce()
+
+    const last = await executeTool('stripe_search_subscriptions', {
+      apiKey: 'sk_test_pagination',
+      query,
+      limit: 100,
+      page: first.output.metadata.next_page,
+    })
+    expect(last).toMatchObject({
+      success: true,
+      output: {
+        subscriptions: [{ id: 'sub_last' }],
+        metadata: { count: 1, has_more: false, next_page: null },
+      },
+    })
+    expect(mockSecureFetchWithPinnedIP).toHaveBeenCalledTimes(2)
+  })
+})
+
 describe('Internal Route Trust', () => {
   let cleanupEnvVars: () => void
 

apps/sim/tools/generated/tool-outputs.ts

@@ -8,7 +8,8 @@ export const stripeListSubscriptionsTool: ToolConfig<
 > = {
   id: 'stripe_list_subscriptions',
   name: 'Stripe List Subscriptions',
-  description: 'List all subscriptions',
+  description:
+    'List one page of subscriptions. Follow starting_after while metadata.has_more is true.',
   version: '1.0.0',
 
   params: {
@@ -37,6 +38,20 @@ export const stripeListSubscriptionsTool: ToolConfig<
       description:
         'Filter by status (active, past_due, unpaid, canceled, incomplete, incomplete_expired, trialing, all)',
     },
+    starting_after: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Next-page cursor: last subscription ID from the previous page. Do not combine with ending_before.',
+    },
+    ending_before: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Previous-page cursor: first subscription ID from the current page. Do not combine with starting_after.',
+    },
     price: {
       type: 'string',
       required: false,
@@ -47,11 +62,16 @@ export const stripeListSubscriptionsTool: ToolConfig<
 
   request: {
     url: (params) => {
+      if (params.starting_after && params.ending_before) {
+        throw new Error('Provide either starting_after or ending_before, not both')
+      }
       const url = new URL('https://api.stripe.com/v1/subscriptions')
       if (params.limit) url.searchParams.append('limit', params.limit.toString())
       if (params.customer) url.searchParams.append('customer', params.customer)
       if (params.status) url.searchParams.append('status', params.status)
       if (params.price) url.searchParams.append('price', params.price)
+      if (params.starting_after) url.searchParams.append('starting_after', params.starting_after)
+      if (params.ending_before) url.searchParams.append('ending_before', params.ending_before)
       return url.toString()
     },
     method: 'GET',

apps/sim/tools/index.test.ts

@@ -1,14 +1,15 @@
-import type { SearchSubscriptionsParams, SubscriptionListResponse } from '@/tools/stripe/types'
+import type { SearchSubscriptionsParams, SubscriptionSearchResponse } from '@/tools/stripe/types'
 import { LIST_METADATA_OUTPUT_PROPERTIES, SUBSCRIPTION_OUTPUT } from '@/tools/stripe/types'
 import type { ToolConfig } from '@/tools/types'
 
 export const stripeSearchSubscriptionsTool: ToolConfig<
   SearchSubscriptionsParams,
-  SubscriptionListResponse
+  SubscriptionSearchResponse
 > = {
   id: 'stripe_search_subscriptions',
   name: 'Stripe Search Subscriptions',
-  description: 'Search for subscriptions using query syntax',
+  description:
+    'Search one page of subscriptions using query syntax. Pass metadata.next_page as page to continue.',
   version: '1.0.0',
 
   params: {
@@ -24,6 +25,13 @@ export const stripeSearchSubscriptionsTool: ToolConfig<
       visibility: 'user-or-llm',
       description: "Search query (e.g., \"status:'active' AND customer:'cus_xxx'\")",
     },
+    page: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'Pagination token from metadata.next_page. Omit for the first page and keep the same query.',
+    },
     limit: {
       type: 'number',
       required: false,
@@ -37,6 +45,7 @@ export const stripeSearchSubscriptionsTool: ToolConfig<
       const url = new URL('https://api.stripe.com/v1/subscriptions/search')
       url.searchParams.append('query', params.query)
       if (params.limit) url.searchParams.append('limit', params.limit.toString())
+      if (params.page) url.searchParams.append('page', params.page)
       return url.toString()
     },
     method: 'GET',
@@ -55,6 +64,7 @@ export const stripeSearchSubscriptionsTool: ToolConfig<
         metadata: {
           count: (data.data || []).length,
           has_more: data.has_more || false,
+          next_page: data.next_page ?? null,
         },
       },
     }
@@ -69,7 +79,15 @@ export const stripeSearchSubscriptionsTool: ToolConfig<
     metadata: {
       type: 'json',
       description: 'Search metadata',
-      properties: LIST_METADATA_OUTPUT_PROPERTIES,
+      properties: {
+        ...LIST_METADATA_OUTPUT_PROPERTIES,
+        next_page: {
+          type: 'string',
+          nullable: true,
+          description:
+            'Token for the next page of search results, or null when there are no more results',
+        },
+      },
     },
   },
 }