update_draft_order

Instructions

Implementation Reference

• src/tools/draft_orders.ts:423-523 (registration)

  Registration of the 'update_draft_order' tool on the MCP server via server.tool() call. Passes schema and handler to McpServer.

  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:427-461 (handler)

  The async handler function for update_draft_order. Builds the GraphQL input from args, calls the Shopify DraftOrderUpdate mutation, handles user errors, and returns a text response with the updated draft's details.

    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}`,
          },
        ],
      };
    },
  );

• src/tools/draft_orders.ts:225-247 (schema)

  Zod-based schema for update_draft_order input arguments. Fields: id (required), lineItems (optional array, replaces all items), customerId, email, note, tags (all optional).

  const updateDraftOrderSchema = {
    id: z
      .string()
      .describe(
        "GID of the draft order to update. Cannot update completed drafts (those are real orders — use the order tools).",
      ),
    lineItems: z
      .array(lineItemSchema)
      .optional()
      .describe(
        "If provided, REPLACES the entire current line-items array — this is a replace, not a merge. To add or remove specific items you must read the current items first and resubmit the full set.",
      ),
    customerId: z
      .string()
      .optional()
      .describe("New customer GID to attach. Pass to swap or set the customer."),
    email: z.string().email().optional().describe("New email for the order."),
    note: z.string().optional().describe("New internal note. Replaces any prior note."),
    tags: z
      .array(z.string())
      .optional()
      .describe("New tag set. Replaces existing tags entirely."),
  };

• src/tools/draft_orders.ts:98-109 (helper)

  The GraphQL mutation string used by update_draft_order. Performs DraftOrderUpdate with id and input variables.

  const UPDATE_DRAFT_ORDER_MUTATION = /* GraphQL */ `
    mutation DraftOrderUpdate($id: ID!, $input: DraftOrderInput!) {
      draftOrderUpdate(id: $id, input: $input) {
        draftOrder {
          id
          name
          status
          totalPriceSet { shopMoney { amount currencyCode } }
        }
        userErrors { field message }
      }
    }

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

  Import of registerDraftOrderTools from the draft_orders module, called at line 62 to register all draft order tools including update_draft_order.

  import { registerDraftOrderTools } from "./tools/draft_orders.js";