cancel_fulfillment

Instructions

Implementation Reference

• src/tools/fulfillment.ts:477-500 (handler)

  The handler function for the cancel_fulfillment tool. Calls the Shopify FulfillmentCancel mutation with the given fulfillment GID and returns the cancellation result.

  server.tool(
    "cancel_fulfillment",
    "Cancel an existing fulfillment — use when an item that was marked shipped won't actually ship (lost in warehouse, address bounced, customer cancelled). Restores remaining quantity on the underlying fulfillment order so the items can be re-fulfilled later. Does NOT issue a refund — combine with order-level refund tools if money needs to come back to the customer. Returns the new fulfillment status (typically CANCELLED).",
    cancelFulfillmentSchema,
    async (args) => {
      const data = await client.graphql<{
        fulfillmentCancel: {
          fulfillment: FulfillmentNode | null;
          userErrors: ShopifyUserError[];
        };
      }>(FULFILLMENT_CANCEL_MUTATION, { id: args.id });
      throwIfUserErrors(data.fulfillmentCancel.userErrors, "fulfillmentCancel");
      const f = data.fulfillmentCancel.fulfillment;
      return {
        content: [
          {
            type: "text" as const,
            text: f
              ? `Cancelled fulfillment ${f.id} — new status: ${f.status}`
              : `Cancelled fulfillment ${args.id}.`,
          },
        ],
      };
    },

• src/tools/fulfillment.ts:232-234 (schema)

  The Zod schema for cancel_fulfillment input, requiring a single 'id' field (the fulfillment GID to cancel).

  const cancelFulfillmentSchema = {
    id: z.string().describe("Fulfillment GID to cancel."),
  };

• src/tools/fulfillment.ts:477-501 (registration)

  Registration of cancel_fulfillment via server.tool() within registerFulfillmentTools, providing the tool name, description, schema, and handler.

  server.tool(
    "cancel_fulfillment",
    "Cancel an existing fulfillment — use when an item that was marked shipped won't actually ship (lost in warehouse, address bounced, customer cancelled). Restores remaining quantity on the underlying fulfillment order so the items can be re-fulfilled later. Does NOT issue a refund — combine with order-level refund tools if money needs to come back to the customer. Returns the new fulfillment status (typically CANCELLED).",
    cancelFulfillmentSchema,
    async (args) => {
      const data = await client.graphql<{
        fulfillmentCancel: {
          fulfillment: FulfillmentNode | null;
          userErrors: ShopifyUserError[];
        };
      }>(FULFILLMENT_CANCEL_MUTATION, { id: args.id });
      throwIfUserErrors(data.fulfillmentCancel.userErrors, "fulfillmentCancel");
      const f = data.fulfillmentCancel.fulfillment;
      return {
        content: [
          {
            type: "text" as const,
            text: f
              ? `Cancelled fulfillment ${f.id} — new status: ${f.status}`
              : `Cancelled fulfillment ${args.id}.`,
          },
        ],
      };
    },
  );

• src/tools/fulfillment.ts:160-170 (helper)

  The GraphQL mutation string (FULFILLMENT_CANCEL_MUTATION) used by the cancel_fulfillment handler to call Shopify's fulfillmentCancel endpoint.

  const FULFILLMENT_CANCEL_MUTATION = /* GraphQL */ `
    mutation FulfillmentCancel($id: ID!) {
      fulfillmentCancel(id: $id) {
        fulfillment {
          id
          status
        }
        userErrors { field message }
      }
    }
  `;