cancel_shipment

Instructions

Implementation Reference

• src/carriers/apc.js:410-429 (handler)

  The actual cancellation logic: sends a PUT request with CancelOrder.Status='CANCELLED' to the APC API and returns success/message.

  export async function cancelConsignment(waybill) {
    // PUT with CancelOrder wrapper and Status=CANCELLED (Edition 2.0.5, §6)
    const body = {
      CancelOrder: {
        Order: {
          Status: 'CANCELLED',
        },
      },
    };
  
    const result = await request('PUT', `/Orders/${waybill}.json?searchtype=CarrierWaybill`, body);
  
    const messages = result?.CancelOrder?.Messages;
    return {
      success: messages?.Code === '121' || /cancelled/i.test(messages?.Description || ''),
      waybill,
      message: messages?.Description || 'Cancellation request sent.',
      raw: result,
    };
  }

• src/index.js:293-319 (registration)

  Registers the MCP tool 'cancel_shipment' with Zod schema (waybill string), calls apc.cancelConsignment, and returns formatted response.

  server.tool(
    'cancel_shipment',
    'Cancel an APC Overnight consignment. Must be done before the parcel is collected/manifested.',
    {
      waybill: z.string().describe('The 22-digit WayBill number to cancel'),
    },
    async ({ waybill }) => {
      try {
        const result = await apc.cancelConsignment(waybill);
        return {
          content: [{
            type: 'text',
            text: JSON.stringify({
              success: result.success,
              waybill,
              message: result.message,
            }, null, 2),
          }],
        };
      } catch (err) {
        return {
          content: [{ type: 'text', text: `Error cancelling shipment: ${err.message}` }],
          isError: true,
        };
      }
    }
  );

• src/index.js:296-298 (schema)

  Input schema for cancel_shipment: a required 'waybill' string described as 'The 22-digit WayBill number to cancel'.

  {
    waybill: z.string().describe('The 22-digit WayBill number to cancel'),
  },

• src/carriers/apc.js:198-222 (helper)

  Generic HTTP request helper used by cancelConsignment to make the PUT call to the APC API.

  async function request(method, path, body = null) {
    const url = `${BASE_URL}${path}`;
  
    const options = {
      method,
      headers: {
        'remote-user':  getAuthHeader(),
        'Content-Type': 'application/json',
        'Accept':       'application/json',
      },
    };
  
    if (body) {
      options.body = JSON.stringify(body);
    }
  
    const response = await fetch(url, options);
  
    if (!response.ok) {
      const error = await response.text();
      throw new Error(`APC API ${response.status}: ${error}`);
    }
  
    return response.json();
  }