list_subscriptions
Retrieve a list of subscriptions with optional filters by status, customer, gateway, date range, and pagination.
Instructions
List subscriptions. GET /subscriptions. Optional: include, query, orderBy, sortBy, filterId, status (exact status), customerId (customer id), companyGatewayId (subscription company gateway id), dateFrom/dateTo (createdAt range; dateFrom from 00:00:00, dateTo through 23:59:59; invalid dates are ignored), itemPerPage, pageNo. Examples: /v1/subscriptions?status=active ; /v1/subscriptions?customerId=123&companyGatewayId=8 ; /v1/subscriptions?dateFrom=2026-01-01&dateTo=2026-01-31 ; /v1/subscriptions?status=paused&customerId=123&dateFrom=2026-01-01&dateTo=2026-01-31.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| include | No | Attributes to include | |
| query | No | Search query | |
| orderBy | No | Sort column | |
| sortBy | No | Sort direction | |
| filterId | No | Filter ID | |
| status | No | Filter by exact subscription status | |
| customerId | No | Filter by customer id | |
| companyGatewayId | No | Filter by subscription company gateway id | |
| dateFrom | No | Filter createdAt from this date (applies from 00:00:00); invalid dates are ignored | |
| dateTo | No | Filter createdAt to this date (applies through 23:59:59); invalid dates are ignored | |
| itemPerPage | No | Items per page | |
| pageNo | No | Page number |
Implementation Reference
- Handler function that parses arguments via zod schema, then calls subscriptionService.listSubscriptions().
async function handler(client: Client, args: Record<string, unknown> | undefined) { const parsed = schema.safeParse(args); if (!parsed.success) { return errorResult(parsed.error.errors.map((e) => e.message).join("; ")); } return handleToolCall(() => subscriptionService.listSubscriptions(client, parsed.data)); } export const listSubscriptionsTool: Tool = { definition, handler, }; - Zod schema and JSON Schema input definition for list_subscriptions tool, defining all optional parameters (include, query, orderBy, sortBy, filterId, status, customerId, companyGatewayId, dateFrom, dateTo, itemPerPage, pageNo).
import { z } from "zod"; import type { Tool } from "../types.js"; import type { Client } from "./helpers.js"; import { errorResult, handleToolCall } from "./helpers.js"; import * as subscriptionService from "../../services/subscriptionServices.js"; const schema = z.object({ include: z.string().optional(), query: z.string().optional(), orderBy: z.string().optional(), sortBy: z.string().optional(), filterId: z.number().int().optional(), status: z.enum(["active", "paused", "requestPayment", "archived"]).optional(), customerId: z.number().int().optional(), companyGatewayId: z.number().int().optional(), dateFrom: z.string().optional(), dateTo: z.string().optional(), itemPerPage: z.number().int().min(1).optional(), pageNo: z.number().int().min(1).optional(), }); const definition = { name: "list_subscriptions", description: "List subscriptions. GET /subscriptions. Optional: include, query, orderBy, sortBy, filterId, status (exact status), customerId (customer id), companyGatewayId (subscription company gateway id), dateFrom/dateTo (createdAt range; dateFrom from 00:00:00, dateTo through 23:59:59; invalid dates are ignored), itemPerPage, pageNo. Examples: /v1/subscriptions?status=active ; /v1/subscriptions?customerId=123&companyGatewayId=8 ; /v1/subscriptions?dateFrom=2026-01-01&dateTo=2026-01-31 ; /v1/subscriptions?status=paused&customerId=123&dateFrom=2026-01-01&dateTo=2026-01-31.", inputSchema: { type: "object" as const, properties: { include: { type: "string", description: "Attributes to include" }, query: { type: "string", description: "Search query" }, orderBy: { type: "string", description: "Sort column" }, sortBy: { type: "string", description: "Sort direction" }, filterId: { type: "number", description: "Filter ID" }, status: { type: "string", enum: ["active", "paused", "requestPayment", "archived"], description: "Filter by exact subscription status", }, customerId: { type: "integer", format: "int64", description: "Filter by customer id", }, companyGatewayId: { type: "integer", format: "int64", description: "Filter by subscription company gateway id", }, dateFrom: { type: "string", format: "date", example: "2026-01-01", description: "Filter createdAt from this date (applies from 00:00:00); invalid dates are ignored", }, dateTo: { type: "string", format: "date", example: "2026-01-31", description: "Filter createdAt to this date (applies through 23:59:59); invalid dates are ignored", }, itemPerPage: { type: "number", description: "Items per page" }, pageNo: { type: "number", description: "Page number" }, }, required: [], }, }; - TypeScript interface ListSubscriptionsParams used by the service layer.
export interface ListSubscriptionsParams { include?: string; query?: string; orderBy?: string; sortBy?: string; filterId?: number; status?: SubscriptionStatus; customerId?: number; companyGatewayId?: number; dateFrom?: string; dateTo?: string; itemPerPage?: number; pageNo?: number; } - Service function listSubscriptions that builds URLSearchParams from params and makes a GET /subscriptions API call.
export async function listSubscriptions( client: Client, params?: ListSubscriptionsParams ): Promise<PaginatedResponse<unknown>> { const search = new URLSearchParams(); if (params?.include) search.append("include", params.include); if (params?.query) search.append("query", params.query); if (params?.orderBy) search.append("orderBy", params.orderBy ?? ""); if (params?.sortBy) search.append("sortBy", params.sortBy ?? ""); if (params?.filterId != null) search.append("filterId", String(params.filterId)); if (params?.status) search.append("status", params.status); if (params?.customerId != null) search.append("customerId", String(params.customerId)); if (params?.companyGatewayId != null) { search.append("companyGatewayId", String(params.companyGatewayId)); } if (params?.dateFrom) search.append("dateFrom", params.dateFrom); if (params?.dateTo) search.append("dateTo", params.dateTo); if (params?.itemPerPage != null) search.append("itemPerPage", String(params.itemPerPage)); if (params?.pageNo != null) search.append("pageNo", String(params.pageNo)); const q = search.toString(); return client.get<PaginatedResponse<unknown>>(`/subscriptions${q ? `?${q}` : ""}`); } - src/tools/subscriptions/index.ts:26-49 (registration)Registration: registerSubscriptionTools() returns listSubscriptionsTool as part of the array of all subscription tools.
/** All 19 subscription tools. */ export function registerSubscriptionTools(): Tool[] { return [ listSubscriptionsTool, getSubscriptionTool, createSubscriptionTool, updateSubscriptionTool, deleteSubscriptionTool, updateSubscriptionStatusTool, getSubscriptionUpcomingChargesTool, getSubscriptionInvoicesTool, getSubscriptionLogsTool, getSubscriptionExternalInvoicesTool, listSubscriptionRatePlansTool, getSubscriptionRatePlanTool, addSubscriptionRatePlanTool, updateSubscriptionRatePlanTool, removeSubscriptionRatePlanTool, getSubscriptionRatePlanChargeTool, addSubscriptionRatePlanChargeTool, updateSubscriptionRatePlanChargeTool, removeSubscriptionRatePlanChargeTool, ]; }