list_customers

Instructions

Implementation Reference

• src/tools/customers.ts:155-178 (handler)

  Tool handler for 'list_customers' — executes Shopify GraphQL query, formats output with customer info (name, email, orders, amount spent), returns text content.

  server.tool(
    "list_customers",
    "List customers in the store, newest first by creation date. Returns each customer's display name, email, lifetime order count, and total amount spent (in shop currency). Supports Shopify's customer query syntax for filtering by email, tag, order count, spend, marketing-consent, account state, and more. Cursor-paginated; pass `after` to advance pages. Use this to find customer GIDs before referencing them in draft orders or to segment for marketing.",
    listCustomersSchema,
    async (args) => {
      const data = await client.graphql<{ customers: Connection<Customer> }>(
        LIST_CUSTOMERS_QUERY,
        { first: args.first, query: args.query, after: args.after },
      );
      const lines = [
        `Found ${data.customers.edges.length} customer(s):`,
        ...data.customers.edges.map(({ node }) => {
          const name = node.displayName ?? "(no name)";
          const email = node.email ?? "(no email)";
          const orders = node.numberOfOrders ?? "0";
          const spent = node.amountSpent
            ? `${node.amountSpent.amount} ${node.amountSpent.currencyCode}`
            : "0";
          return `  ${name} <${email}> — ${orders} orders, ${spent} — ${node.id}`;
        }),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

• src/tools/customers.ts:59-79 (schema)

  Input schema for list_customers: accepts first (page size, default 20), query (optional filter string), after (optional pagination cursor).

  const listCustomersSchema = {
    first: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(20)
      .describe("Page size (1-100)."),
    query: z
      .string()
      .optional()
      .describe(
        "Shopify customer query syntax. Examples: 'email:*@gmail.com' (domain match), 'tag:vip' (tagged), 'orders_count:>=5' (repeat customer), 'amount_spent:>=500' (high value), 'state:enabled', 'accepts_marketing:true'. Combine with AND/OR.",
      ),
    after: z
      .string()
      .optional()
      .describe(
        "Cursor from the previous page's pageInfo for pagination. Omit on the first call.",
      ),
  };

• src/tools/customers.ts:155-178 (registration)

  Registration of 'list_customers' via server.tool() in registerCustomerTools function.

  server.tool(
    "list_customers",
    "List customers in the store, newest first by creation date. Returns each customer's display name, email, lifetime order count, and total amount spent (in shop currency). Supports Shopify's customer query syntax for filtering by email, tag, order count, spend, marketing-consent, account state, and more. Cursor-paginated; pass `after` to advance pages. Use this to find customer GIDs before referencing them in draft orders or to segment for marketing.",
    listCustomersSchema,
    async (args) => {
      const data = await client.graphql<{ customers: Connection<Customer> }>(
        LIST_CUSTOMERS_QUERY,
        { first: args.first, query: args.query, after: args.after },
      );
      const lines = [
        `Found ${data.customers.edges.length} customer(s):`,
        ...data.customers.edges.map(({ node }) => {
          const name = node.displayName ?? "(no name)";
          const email = node.email ?? "(no email)";
          const orders = node.numberOfOrders ?? "0";
          const spent = node.amountSpent
            ? `${node.amountSpent.amount} ${node.amountSpent.currencyCode}`
            : "0";
          return `  ${name} <${email}> — ${orders} orders, ${spent} — ${node.id}`;
        }),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

• src/tools/customers.ts:8-27 (helper)

  GraphQL query used by list_customers to fetch customers from Shopify, sorted by creation date descending, with pagination support.

  const LIST_CUSTOMERS_QUERY = /* GraphQL */ `
    query ListCustomers($first: Int!, $after: String, $query: String) {
      customers(first: $first, after: $after, query: $query, sortKey: CREATED_AT, reverse: true) {
        edges {
          cursor
          node {
            id
            firstName
            lastName
            email
            displayName
            numberOfOrders
            amountSpent { amount currencyCode }
            createdAt
          }
        }
        pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
      }
    }
  `;