list_draft_orders

Instructions

Implementation Reference

• src/tools/draft_orders.ts:300-321 (handler)

  The handler function for the 'list_draft_orders' tool. Makes a GraphQL call using LIST_DRAFT_ORDERS_QUERY with pagination args (first, after, query), maps results to a text summary, and returns it as MCP content.

    async (args) => {
      const data = await client.graphql<{
        draftOrders: Connection<DraftOrder>;
      }>(LIST_DRAFT_ORDERS_QUERY, {
        first: args.first,
        after: args.after,
        query: args.query,
      });
      const lines = [
        `Found ${data.draftOrders.edges.length} draft order(s):`,
        ...data.draftOrders.edges.map(({ node }) => {
          const total = `${node.totalPriceSet.shopMoney.amount} ${node.totalPriceSet.shopMoney.currencyCode}`;
          const customer = node.customer?.displayName ?? "(no customer)";
          const completed = node.order
            ? ` → order ${node.order.name}`
            : "";
          return `  ${node.name} [${node.status}] ${total} — ${customer}${completed} — ${node.id}`;
        }),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

• src/tools/draft_orders.ts:161-179 (schema)

  Zod schema for list_draft_orders input: 'first' (page size 1-100, default 20), 'query' (optional Shopify query syntax), and 'after' (optional cursor for pagination).

  const listDraftOrdersSchema = {
    first: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(20)
      .describe("Page size (1-100)."),
    query: z
      .string()
      .optional()
      .describe(
        "Shopify draft order query syntax. Examples: 'status:OPEN' (not yet completed), 'status:COMPLETED', 'customer_id:1234567890', 'tag:wholesale', 'updated_at:>=2026-01-01'.",
      ),
    after: z
      .string()
      .optional()
      .describe("Cursor from the previous page's pageInfo. Omit on the first call."),
  };

• src/tools/draft_orders.ts:296-321 (registration)

  Registration of 'list_draft_orders' via server.tool() in the registerDraftOrderTools function, with the name, description, schema, and handler.

  server.tool(
    "list_draft_orders",
    "List draft orders (carts/quotes that haven't yet been completed into real orders), most recently updated first. Returns each draft's name (e.g. 'D1023'), status (OPEN/COMPLETED/INVOICE_SENT), total price, customer name, and whether it's already been converted to an order. Supports Shopify's draft-order query syntax for filtering by status, customer, tag, or update time. Cursor-paginated.",
    listDraftOrdersSchema,
    async (args) => {
      const data = await client.graphql<{
        draftOrders: Connection<DraftOrder>;
      }>(LIST_DRAFT_ORDERS_QUERY, {
        first: args.first,
        after: args.after,
        query: args.query,
      });
      const lines = [
        `Found ${data.draftOrders.edges.length} draft order(s):`,
        ...data.draftOrders.edges.map(({ node }) => {
          const total = `${node.totalPriceSet.shopMoney.amount} ${node.totalPriceSet.shopMoney.currencyCode}`;
          const customer = node.customer?.displayName ?? "(no customer)";
          const completed = node.order
            ? ` → order ${node.order.name}`
            : "";
          return `  ${node.name} [${node.status}] ${total} — ${customer}${completed} — ${node.id}`;
        }),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

• src/server.ts:62-62 (registration)

  The top-level call to registerDraftOrderTools from the server setup, which registers all draft order tools including list_draft_orders.

  registerDraftOrderTools(s, shopify);

• src/tools/draft_orders.ts:33-53 (helper)

  The GraphQL query used by list_draft_orders to fetch draft orders with pagination, sorted by UPDATED_AT descending.

  const LIST_DRAFT_ORDERS_QUERY = /* GraphQL */ `
    query ListDraftOrders($first: Int!, $after: String, $query: String) {
      draftOrders(first: $first, after: $after, query: $query, sortKey: UPDATED_AT, reverse: true) {
        edges {
          cursor
          node {
            id
            name
            status
            totalPriceSet { shopMoney { amount currencyCode } }
            customer { id displayName email }
            createdAt
            updatedAt
            completedAt
            order { id name }
          }
        }
        pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
      }
    }
  `;