get_draft_order

Instructions

Implementation Reference

• src/tools/draft_orders.ts:323-371 (handler)

  The handler for the 'get_draft_order' tool. Uses server.tool() to register 'get_draft_order', fetches a single draft order via GraphQL query GET_DRAFT_ORDER_QUERY, and returns a formatted text summary with status, total, customer, invoice URL, line items, and completed order info.

  server.tool(
    "get_draft_order",
    "Fetch a single draft order with full details: status, customer, line items (with quantity, title, and unit price), invoice URL, and the resulting real order if it's already been completed. Use to inspect a draft before calling update_draft_order or complete_draft_order. Returns a friendly text summary.",
    getDraftOrderSchema,
    async (args) => {
      const data = await client.graphql<{ draftOrder: DraftOrder | null }>(
        GET_DRAFT_ORDER_QUERY,
        { id: args.id },
      );
      if (!data.draftOrder) {
        return {
          content: [
            { type: "text" as const, text: `Draft order not found: ${args.id}` },
          ],
        };
      }
      const d = data.draftOrder;
      const total = `${d.totalPriceSet.shopMoney.amount} ${d.totalPriceSet.shopMoney.currencyCode}`;
      const customer = d.customer
        ? `${d.customer.displayName ?? ""} <${d.customer.email ?? ""}>`
        : "(no customer)";
      const lineItemLines =
        d.lineItems?.edges.map(({ node }) => {
          const price = node.originalUnitPriceSet
            ? `@ ${node.originalUnitPriceSet.shopMoney.amount} ${node.originalUnitPriceSet.shopMoney.currencyCode}`
            : "";
          return `    - ${node.quantity}× ${node.title} ${price}`.trim();
        }) ?? [];
      return {
        content: [
          {
            type: "text" as const,
            text: [
              `${d.name} [${d.status}]`,
              `  ID: ${d.id}`,
              `  Total: ${total}`,
              `  Customer: ${customer}`,
              d.invoiceUrl ? `  Invoice: ${d.invoiceUrl}` : "",
              d.order ? `  Completed as order: ${d.order.name} (${d.order.id})` : "",
              "  Line items:",
              ...lineItemLines,
            ]
              .filter(Boolean)
              .join("\n"),
          },
        ],
      };
    },
  );

• src/tools/draft_orders.ts:181-187 (schema)

  Input schema for get_draft_order: requires a single `id` string parameter describing the draft order GID (e.g. 'gid://shopify/DraftOrder/12345').

  const getDraftOrderSchema = {
    id: z
      .string()
      .describe(
        "Draft order GID, e.g. 'gid://shopify/DraftOrder/12345'. Get one from list_draft_orders.",
      ),
  };

• src/tools/draft_orders.ts:292-524 (registration)

  The registerDraftOrderTools function that registers all draft order tools (including get_draft_order) on the McpServer instance. Called from src/server.ts line 62.

  export function registerDraftOrderTools(
    server: McpServer,
    client: ShopifyClient,
  ): void {
    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") }] };
      },
    );
  
    server.tool(
      "get_draft_order",
      "Fetch a single draft order with full details: status, customer, line items (with quantity, title, and unit price), invoice URL, and the resulting real order if it's already been completed. Use to inspect a draft before calling update_draft_order or complete_draft_order. Returns a friendly text summary.",
      getDraftOrderSchema,
      async (args) => {
        const data = await client.graphql<{ draftOrder: DraftOrder | null }>(
          GET_DRAFT_ORDER_QUERY,
          { id: args.id },
        );
        if (!data.draftOrder) {
          return {
            content: [
              { type: "text" as const, text: `Draft order not found: ${args.id}` },
            ],
          };
        }
        const d = data.draftOrder;
        const total = `${d.totalPriceSet.shopMoney.amount} ${d.totalPriceSet.shopMoney.currencyCode}`;
        const customer = d.customer
          ? `${d.customer.displayName ?? ""} <${d.customer.email ?? ""}>`
          : "(no customer)";
        const lineItemLines =
          d.lineItems?.edges.map(({ node }) => {
            const price = node.originalUnitPriceSet
              ? `@ ${node.originalUnitPriceSet.shopMoney.amount} ${node.originalUnitPriceSet.shopMoney.currencyCode}`
              : "";
            return `    - ${node.quantity}× ${node.title} ${price}`.trim();
          }) ?? [];
        return {
          content: [
            {
              type: "text" as const,
              text: [
                `${d.name} [${d.status}]`,
                `  ID: ${d.id}`,
                `  Total: ${total}`,
                `  Customer: ${customer}`,
                d.invoiceUrl ? `  Invoice: ${d.invoiceUrl}` : "",
                d.order ? `  Completed as order: ${d.order.name} (${d.order.id})` : "",
                "  Line items:",
                ...lineItemLines,
              ]
                .filter(Boolean)
                .join("\n"),
            },
          ],
        };
      },
    );
  
      server.tool(
      "create_draft_order",
      "Create a new draft order — Shopify's term for an editable cart/quote not yet placed as an order. Each line item is EITHER a variant reference (variantId + quantity) for catalog products, OR a custom item (title + originalUnitPrice + quantity) for one-off charges or services not in the catalog. Optionally attach a customer, email, internal note, tags, and choose whether to copy the customer's default address. Returns the new draft's GID and an invoice URL the customer can use to pay. Drafts stay OPEN until you call complete_draft_order or send the invoice.",
      createDraftOrderSchema,
      async (args) => {
        const input: Record<string, unknown> = {
          lineItems: mapLineItemsForInput(args.lineItems),
        };
        if (args.customerId) input.customerId = args.customerId;
        if (args.email) input.email = args.email;
        if (args.note) input.note = args.note;
        if (args.tags) input.tags = args.tags;
        if (args.useCustomerDefaultAddress !== undefined) {
          input.useCustomerDefaultAddress = args.useCustomerDefaultAddress;
        }
  
        const data = await client.graphql<{
          draftOrderCreate: {
            draftOrder: DraftOrder | null;
            userErrors: ShopifyUserError[];
          };
        }>(CREATE_DRAFT_ORDER_MUTATION, { input });
        throwIfUserErrors(data.draftOrderCreate.userErrors, "draftOrderCreate");
        const d = data.draftOrderCreate.draftOrder;
        if (!d) {
          return {
            content: [
              { type: "text" as const, text: "draftOrderCreate returned no draft order." },
            ],
          };
        }
        const total = `${d.totalPriceSet.shopMoney.amount} ${d.totalPriceSet.shopMoney.currencyCode}`;
        return {
          content: [
            {
              type: "text" as const,
              text: [
                `Created draft order ${d.name} [${d.status}]`,
                `  ID: ${d.id}`,
                `  Total: ${total}`,
                d.invoiceUrl ? `  Invoice: ${d.invoiceUrl}` : "",
              ]
                .filter(Boolean)
                .join("\n"),
            },
          ],
        };
      },
    );
  
    server.tool(
      "update_draft_order",
      "Modify an existing OPEN draft order's customer, email, note, tags, or line items. Important: if `lineItems` is provided, it REPLACES the existing items entirely (not a merge or append) — read the current items first if you need to preserve any. Cannot update completed drafts; those are real orders. To pause and pick up a draft later, leave it OPEN and re-invoke update later; nothing here triggers payment.",
      updateDraftOrderSchema,
      async (args) => {
        const input: Record<string, unknown> = {};
        const mapped = mapLineItemsForInput(args.lineItems);
        if (mapped) input.lineItems = mapped;
        if (args.customerId) input.customerId = args.customerId;
        if (args.email) input.email = args.email;
        if (args.note) input.note = args.note;
        if (args.tags) input.tags = args.tags;
  
        const data = await client.graphql<{
          draftOrderUpdate: {
            draftOrder: DraftOrder | null;
            userErrors: ShopifyUserError[];
          };
        }>(UPDATE_DRAFT_ORDER_MUTATION, { id: args.id, input });
        throwIfUserErrors(data.draftOrderUpdate.userErrors, "draftOrderUpdate");
        const d = data.draftOrderUpdate.draftOrder;
        if (!d) {
          return {
            content: [
              { type: "text" as const, text: "draftOrderUpdate returned no draft order." },
            ],
          };
        }
        const total = `${d.totalPriceSet.shopMoney.amount} ${d.totalPriceSet.shopMoney.currencyCode}`;
        return {
          content: [
            {
              type: "text" as const,
              text: `Updated draft order ${d.name} [${d.status}] — Total: ${total}`,
            },
          ],
        };
      },
    );
  
    server.tool(
      "complete_draft_order",
      "Convert an OPEN draft order into a real Shopify order. With paymentPending=false (default), Shopify attempts to capture payment immediately; the call fails if no payment method is on file. With paymentPending=true, the order is created in payment-pending status — useful when collecting payment offline (cash, bank transfer, manual processing). Once completed, the draft transitions to COMPLETED and the new order's GID is returned. The transition is one-way: completed drafts cannot be re-opened or edited via draft tools (use the order tools, or refund/cancel for the resulting order).",
      completeDraftOrderSchema,
      async (args) => {
        const data = await client.graphql<{
          draftOrderComplete: {
            draftOrder: DraftOrder | null;
            userErrors: ShopifyUserError[];
          };
        }>(COMPLETE_DRAFT_ORDER_MUTATION, {
          id: args.id,
          paymentPending: args.paymentPending ?? false,
        });
        throwIfUserErrors(data.draftOrderComplete.userErrors, "draftOrderComplete");
        const d = data.draftOrderComplete.draftOrder;
        if (!d) {
          return {
            content: [
              { type: "text" as const, text: "draftOrderComplete returned no draft order." },
            ],
          };
        }
        const orderInfo = d.order
          ? ` → order ${d.order.name} (${d.order.id})`
          : "";
        return {
          content: [
            {
              type: "text" as const,
              text: `Completed draft order ${d.name} [${d.status}]${orderInfo}`,
            },
          ],
        };
      },
    );
  
    server.tool(
      "delete_draft_order",
      "Permanently delete a draft order. Only OPEN/INVOICE_SENT drafts can be deleted — completed drafts are real orders and orders cannot be deleted (cancel them instead). Irreversible. Returns the deleted GID, or a no-op message if the GID didn't match anything.",
      deleteDraftOrderSchema,
      async (args) => {
        const data = await client.graphql<{
          draftOrderDelete: {
            deletedId: string | null;
            userErrors: ShopifyUserError[];
          };
        }>(DELETE_DRAFT_ORDER_MUTATION, { input: { id: args.id } });
        throwIfUserErrors(data.draftOrderDelete.userErrors, "draftOrderDelete");
        return {
          content: [
            {
              type: "text" as const,
              text: data.draftOrderDelete.deletedId
                ? `Deleted draft order ${data.draftOrderDelete.deletedId}.`
                : "No draft order matched; nothing deleted.",
            },
          ],
        };
      },
    );
  }

• src/tools/draft_orders.ts:55-81 (helper)

  GET_DRAFT_ORDER_QUERY - GraphQL query used by the get_draft_order handler to fetch a single draft order by ID with full details (status, customer, line items, invoice URL, order info).

  const GET_DRAFT_ORDER_QUERY = /* GraphQL */ `
    query GetDraftOrder($id: ID!) {
      draftOrder(id: $id) {
        id
        name
        status
        invoiceUrl
        totalPriceSet { shopMoney { amount currencyCode } }
        subtotalPriceSet { shopMoney { amount currencyCode } }
        customer { id displayName email }
        lineItems(first: 50) {
          edges {
            node {
              title
              quantity
              originalUnitPriceSet { shopMoney { amount currencyCode } }
              variant { id sku }
            }
          }
        }
        createdAt
        updatedAt
        completedAt
        order { id name }
      }
    }
  `;

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

  Registration call site in src/server.ts: registerDraftOrderTools(s, shopify) which wires the draft order tools (including get_draft_order) into the MCP server.

  registerDraftOrderTools(s, shopify);