complete_draft_order

Instructions

Implementation Reference

• src/tools/draft_orders.ts:463-498 (handler)

  The complete_draft_order tool handler: converts an OPEN draft order into a real Shopify order via the draftOrderComplete GraphQL mutation, with an optional paymentPending flag. Returns a success message with the draft order name, status, and the resulting order's name/ID if available.

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

• src/tools/draft_orders.ts:249-259 (schema)

  The input schema (completeDraftOrderSchema) for the complete_draft_order tool, defining 'id' (required, GID of OPEN draft order) and 'paymentPending' (optional boolean, default false).

  const completeDraftOrderSchema = {
    id: z
      .string()
      .describe("GID of an OPEN draft order. Already-completed drafts are rejected."),
    paymentPending: z
      .boolean()
      .optional()
      .describe(
        "If true, the resulting order is marked payment-pending — Shopify creates the order but does NOT capture payment. Use when you'll collect payment offline (cash, bank transfer, manual card auth) or via a separate flow. Default false (attempts to capture immediately).",
      ),
  };

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

  The registerDraftOrderTools function registers all draft order tools (including 'complete_draft_order') on the MCP server. 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:112-124 (helper)

  The COMPLETE_DRAFT_ORDER_MUTATION GraphQL mutation used by the handler to call draftOrderComplete on Shopify's Admin API.

  const COMPLETE_DRAFT_ORDER_MUTATION = /* GraphQL */ `
    mutation DraftOrderComplete($id: ID!, $paymentPending: Boolean) {
      draftOrderComplete(id: $id, paymentPending: $paymentPending) {
        draftOrder {
          id
          name
          status
          order { id name }
        }
        userErrors { field message }
      }
    }
  `;