get-customer-orders

Retrieve order history for a specific Shopify customer using their customer ID, with optional limit control for managing data volume.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`customerId`	Yes	Shopify customer ID, numeric excluding gid prefix
`limit`	No

Implementation Reference

src/tools/getCustomerOrders.ts:26-167 (handler)

The execute function that implements the core logic for fetching customer orders from Shopify GraphQL API. It validates input, constructs a GraphQL query to fetch orders filtered by customer ID, and returns formatted order data including customer details, line items, pricing, and fulfillment status.

execute: async (input: GetCustomerOrdersInput) => {
  try {
    const { customerId, limit } = input;

    // Convert the numeric customer ID to the GID format
    const customerGid = `gid://shopify/Customer/${customerId}`;

    // Query to get orders for a specific customer
    const query = gql`
      query GetCustomerOrders($query: String!, $first: Int!) {
        orders(query: $query, first: $first) {
          edges {
            node {
              id
              name
              createdAt
              displayFinancialStatus
              displayFulfillmentStatus
              totalPriceSet {
                shopMoney {
                  amount
                  currencyCode
                }
              }
              subtotalPriceSet {
                shopMoney {
                  amount
                  currencyCode
                }
              }
              totalShippingPriceSet {
                shopMoney {
                  amount
                  currencyCode
                }
              }
              totalTaxSet {
                shopMoney {
                  amount
                  currencyCode
                }
              }
              customer {
                id
                firstName
                lastName
                email
              }
              lineItems(first: 5) {
                edges {
                  node {
                    id
                    title
                    quantity
                    originalTotalSet {
                      shopMoney {
                        amount
                        currencyCode
                      }
                    }
                    variant {
                      id
                      title
                      sku
                    }
                  }
                }
              }
              tags
              note
            }
          }
        }
      }
    `;

    // We use the query parameter to filter orders by customer ID
    const variables = {
      query: `customer_id:${customerId}`,
      first: limit
    };

    const data = (await shopifyClient.request(query, variables)) as {
      orders: any;
    };

    // Extract and format order data
    const orders = data.orders.edges.map((edge: any) => {
      const order = edge.node;

      // Format line items
      const lineItems = order.lineItems.edges.map((lineItemEdge: any) => {
        const lineItem = lineItemEdge.node;
        return {
          id: lineItem.id,
          title: lineItem.title,
          quantity: lineItem.quantity,
          originalTotal: lineItem.originalTotalSet.shopMoney,
          variant: lineItem.variant
            ? {
                id: lineItem.variant.id,
                title: lineItem.variant.title,
                sku: lineItem.variant.sku
              }
            : null
        };
      });

      return {
        id: order.id,
        name: order.name,
        createdAt: order.createdAt,
        financialStatus: order.displayFinancialStatus,
        fulfillmentStatus: order.displayFulfillmentStatus,
        totalPrice: order.totalPriceSet.shopMoney,
        subtotalPrice: order.subtotalPriceSet.shopMoney,
        totalShippingPrice: order.totalShippingPriceSet.shopMoney,
        totalTax: order.totalTaxSet.shopMoney,
        customer: order.customer
          ? {
              id: order.customer.id,
              firstName: order.customer.firstName,
              lastName: order.customer.lastName,
              email: order.customer.email
            }
          : null,
        lineItems,
        tags: order.tags,
        note: order.note
      };
    });

    return { orders };
  } catch (error) {
    console.error("Error fetching customer orders:", error);
    throw new Error(
      `Failed to fetch customer orders: ${
        error instanceof Error ? error.message : String(error)
      }`
    );
  }
}

src/tools/getCustomerOrders.ts:6-11 (schema)

Input schema definition using Zod for validating the get-customer-orders tool parameters. Requires a numeric customerId string and has an optional limit parameter defaulting to 10.

const GetCustomerOrdersInputSchema = z.object({
  customerId: z.string().regex(/^\d+$/, "Customer ID must be numeric"),
  limit: z.number().default(10)
});

type GetCustomerOrdersInput = z.infer<typeof GetCustomerOrdersInputSchema>;

src/tools/getCustomerOrders.ts:16-24 (handler)

Tool object definition containing the name, description, schema reference, and initialize method for setting up the GraphQL client dependency.

const getCustomerOrders = {
  name: "get-customer-orders",
  description: "Get orders for a specific customer",
  schema: GetCustomerOrdersInputSchema,

  // Add initialize method to set up the GraphQL client
  initialize(client: GraphQLClient) {
    shopifyClient = client;
  },

src/index.ts:202-217 (registration)

MCP server tool registration for get-customer-orders. Defines the input schema (customerId as numeric string and limit), and provides the handler that calls getCustomerOrders.execute and returns JSON results.

server.tool(
  "get-customer-orders",
  {
    customerId: z
      .string()
      .regex(/^\d+$/, "Customer ID must be numeric")
      .describe("Shopify customer ID, numeric excluding gid prefix"),
    limit: z.number().default(10)
  },
  async (args) => {
    const result = await getCustomerOrders.execute(args);
    return {
      content: [{ type: "text", text: JSON.stringify(result) }]
    };
  }
);

src/index.ts:69-69 (registration)
Tool initialization where the Shopify GraphQL client is passed to getCustomerOrders to enable API communication.
```
getCustomerOrders.initialize(shopifyClient);
```

Shopify MCP Server