cancel_order

Instructions

Implementation Reference

• src/tools/orders.ts:473-500 (handler)

  The handler function that executes the cancel_order tool logic. Calls the ORDER_CANCEL_MUTATION GraphQL mutation with the args (id, reason, refund, restock, staffNote, notifyCustomer), throws on user errors, and returns a success message with the async job info.

    async (args) => {
      const data = await client.graphql<{
        orderCancel: {
          job: { id: string; done: boolean } | null;
          orderCancelUserErrors: ShopifyUserError[];
        };
      }>(ORDER_CANCEL_MUTATION, {
        orderId: toGid(args.id, "Order"),
        reason: args.reason,
        refund: args.refund,
        restock: args.restock,
        staffNote: args.staffNote,
        notifyCustomer: args.notifyCustomer,
      });
      throwIfUserErrors(data.orderCancel.orderCancelUserErrors, "orderCancel");
      const job = data.orderCancel.job;
      return {
        content: [
          {
            type: "text" as const,
            text: job
              ? `Queued cancellation of ${args.id} (reason: ${args.reason}). Job: ${job.id} (done=${job.done})`
              : `Cancelled ${args.id} (reason: ${args.reason}).`,
          },
        ],
      };
    },
  );

• src/tools/orders.ts:245-274 (schema)

  Input schema for cancel_order. Defines parameters: id (Order GID or numeric ID), reason (enum: CUSTOMER, FRAUD, INVENTORY, DECLINED, OTHER, STAFF), refund (boolean, default true), restock (boolean, default true), staffNote (optional string), and notifyCustomer (optional boolean).

  const cancelOrderSchema = {
    id: z
      .string()
      .describe("Order GID or numeric ID to cancel. The order must not already be cancelled."),
    reason: z
      .enum(["CUSTOMER", "FRAUD", "INVENTORY", "DECLINED", "OTHER", "STAFF"])
      .describe(
        "Why the order is being cancelled. CUSTOMER (customer requested), FRAUD (suspected fraud), INVENTORY (out of stock), DECLINED (payment declined), STAFF (staff decision), OTHER.",
      ),
    refund: z
      .boolean()
      .default(true)
      .describe(
        "Whether to refund the customer's payment as part of cancellation. true = refund any captured payment in full; false = cancel without refunding (use for unpaid orders, or when you'll handle the refund separately).",
      ),
    restock: z
      .boolean()
      .default(true)
      .describe(
        "Whether to restock cancelled line items back to inventory. true = decrement inventory back; false = leave inventory as-is (use when items were physically lost/damaged).",
      ),
    staffNote: z
      .string()
      .optional()
      .describe("Internal note about the cancellation reason. Visible to staff only."),
    notifyCustomer: z
      .boolean()
      .optional()
      .describe("Send the customer a cancellation email. Default false."),
  };

• src/tools/orders.ts:469-500 (registration)

  Registration of the 'cancel_order' tool via server.tool() inside the registerOrderTools function. Registers the tool name, description, schema (cancelOrderSchema), and the async handler.

  server.tool(
    "cancel_order",
    "Cancel a Shopify order. Triggers an async job (the response includes a jobId; cancellation finishes shortly after the call returns). Combine with `refund: true` to issue a full refund of any captured payment, or `refund: false` if the order is unpaid or you'll handle refunds separately via refund_order. `restock: true` restores cancelled line items back to inventory; set false if items were physically lost/damaged. `notifyCustomer: true` sends the cancellation email. Cannot cancel an already-cancelled order or one with active fulfillments still in flight (cancel those fulfillments first via cancel_fulfillment).",
    cancelOrderSchema,
    async (args) => {
      const data = await client.graphql<{
        orderCancel: {
          job: { id: string; done: boolean } | null;
          orderCancelUserErrors: ShopifyUserError[];
        };
      }>(ORDER_CANCEL_MUTATION, {
        orderId: toGid(args.id, "Order"),
        reason: args.reason,
        refund: args.refund,
        restock: args.restock,
        staffNote: args.staffNote,
        notifyCustomer: args.notifyCustomer,
      });
      throwIfUserErrors(data.orderCancel.orderCancelUserErrors, "orderCancel");
      const job = data.orderCancel.job;
      return {
        content: [
          {
            type: "text" as const,
            text: job
              ? `Queued cancellation of ${args.id} (reason: ${args.reason}). Job: ${job.id} (done=${job.done})`
              : `Cancelled ${args.id} (reason: ${args.reason}).`,
          },
        ],
      };
    },
  );

• src/tools/orders.ts:74-95 (helper)

  ORDER_CANCEL_MUTATION — the GraphQL mutation for cancelling an order with parameters: orderId, reason (OrderCancelReason), refund, restock, staffNote, and notifyCustomer.

  const ORDER_CANCEL_MUTATION = /* GraphQL */ `
    mutation OrderCancel(
      $orderId: ID!
      $reason: OrderCancelReason!
      $refund: Boolean!
      $restock: Boolean!
      $staffNote: String
      $notifyCustomer: Boolean
    ) {
      orderCancel(
        orderId: $orderId
        reason: $reason
        refund: $refund
        restock: $restock
        staffNote: $staffNote
        notifyCustomer: $notifyCustomer
      ) {
        job { id done }
        orderCancelUserErrors { field message code }
      }
    }
  `;

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

  Top-level registration call: registerOrderTools(s, shopify) wires up the cancel_order tool into the MCP server.

  registerOrderTools(s, shopify);