get_customer_invoices

Instructions

Implementation Reference

• src/tools/customers/getCustomerInvoices.ts:62-80 (handler)

  Handler function that validates input via Zod schema, then delegates to customerService.getCustomerInvoices to execute the API call.

  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("; "));
    }
    const { customerId, pageNo, itemPerPage, include, status, dateFrom, dateTo, subscriptionId } =
      parsed.data;
    return handleToolCall(() =>
      customerService.getCustomerInvoices(client, customerId, {
        pageNo,
        itemPerPage,
        include,
        status,
        dateFrom,
        dateTo,
        subscriptionId,
      })
    );
  }

• src/tools/customers/getCustomerInvoices.ts:7-27 (schema)

  Zod validation schema defining the input parameters for get_customer_invoices.

  const schema = z.object({
    customerId: z.string().min(1, "customerId is required"),
    pageNo: z.number().optional(),
    itemPerPage: z.number().optional(),
    include: z.string().optional(),
    status: z
      .enum([
        "authorized",
        "posted",
        "canceled",
        "partialPaid",
        "paid",
        "voided",
        "refund",
        "partialRefund",
      ])
      .optional(),
    dateFrom: z.string().optional(),
    dateTo: z.string().optional(),
    subscriptionId: z.string().optional(),
  });

• src/tools/customers/getCustomerInvoices.ts:29-60 (schema)

  MCP tool definition/registration metadata with name, description, and JSON Schema input schema.

  const definition = {
    name: "get_customer_invoices",
    description:
      "List invoices for a customer. GET /customers/{customerId}/invoices. Supports pagination (pageNo, itemPerPage), include (e.g. detail, transactions), status (authorized|posted|canceled|partialPaid|paid|voided|refund|partialRefund), dateFrom, dateTo, and subscriptionId.",
    inputSchema: {
      type: "object" as const,
      properties: {
        customerId: { type: "string", description: "Customer ID (required)" },
        pageNo: { type: "number", description: "Page number (default: 1)" },
        itemPerPage: { type: "number", description: "Items per page (default: 25)" },
        include: { type: "string", description: "Comma-separated: detail, transactions, billruns, externalInvoices" },
        status: {
          type: "string",
          enum: [
            "authorized",
            "posted",
            "canceled",
            "partialPaid",
            "paid",
            "voided",
            "refund",
            "partialRefund",
          ],
          description: "Filter by invoice status",
        },
        dateFrom: { type: "string", format: "date", description: "Filter invoices from date (YYYY-MM-DD)" },
        dateTo: { type: "string", format: "date", description: "Filter invoices to date (YYYY-MM-DD)" },
        subscriptionId: { type: "string", description: "Filter by subscription ID" },
      },
      required: ["customerId"],
    },
  };

• src/tools/customers/index.ts:31-55 (registration)

  Registration of getCustomerInvoicesTool in the customer tools registry, making it available via registerCustomerTools().

  export function registerCustomerTools(): Tool[] {
    return [
      listCustomersTool,
      getCustomerTool,
      createCustomerTool,
      updateCustomerTool,
      deleteCustomerTool,
      getCustomerInvoicesTool,
      getCustomerUnpaidInvoicesTool,
      getCustomerSubscriptionsTool,
      getCustomerLogsTool,
      listCustomerAddressesTool,
      getCustomerAddressTool,
      createCustomerAddressTool,
      updateCustomerAddressTool,
      deleteCustomerAddressTool,
      listCustomerPaymentMethodsTool,
      getCustomerPaymentMethodTool,
      createCustomerPaymentMethodTool,
      updateCustomerPaymentMethodTool,
      deleteCustomerPaymentMethodTool,
      listCustomerChargesCreditsTool,
      createCustomerChargeCreditTool,
      deleteCustomerChargeCreditTool,
    ];

• src/services/customerServices.ts:244-258 (helper)

  Service function that performs the actual HTTP GET request to /customers/{customerId}/invoices with query parameters for filtering and pagination.

  export async function getCustomerInvoices(
    client: Client,
    customerId: string,
    params?: CustomerInvoiceListParams
  ): Promise<PaginatedResponse<Invoice>> {
    const search = new URLSearchParams();
    if (params) appendParams(search, params as Record<string, unknown>);
    if (params?.status) search.append("status", params.status);
    if (params?.dateFrom) search.append("dateFrom", params.dateFrom);
    if (params?.dateTo) search.append("dateTo", params.dateTo);
    if (params?.subscriptionId) search.append("subscriptionId", params.subscriptionId);
    return client.get<PaginatedResponse<Invoice>>(
      `/customers/${customerId}/invoices${queryString(search)}`
    );
  }