update_transaction

Instructions

Implementation Reference

• src/tools/transactions.ts:103-128 (schema)

  Schema defining the writable fields for updating a transaction (all optional).

  const updateTransactionFieldsSchema = z.object({
      date: dateString.optional(),
      amount: z.coerce.number().optional(),
      currency: z.string().length(3).optional(),
      payee: z.string().max(140).optional(),
      category_id: z.coerce.number().nullable().optional(),
      notes: z.string().max(350).nullable().optional(),
      manual_account_id: z.coerce.number().nullable().optional(),
      plaid_account_id: z.coerce.number().nullable().optional(),
      recurring_id: z.coerce.number().nullable().optional(),
      status: writeStatusEnum.optional(),
      tag_ids: z
          .array(z.coerce.number())
          .optional()
          .describe(
              "Replaces all existing tags on the transaction. Mutually exclusive with additional_tag_ids.",
          ),
      additional_tag_ids: z
          .array(z.coerce.number())
          .optional()
          .describe(
              "Adds these tags to the existing transaction tags. Mutually exclusive with tag_ids.",
          ),
      external_id: z.string().max(75).nullable().optional(),
      custom_metadata: z.record(z.unknown()).nullable().optional(),
  });

• src/tools/transactions.ts:393-412 (handler)

  Handler function that executes the update_transaction tool logic: sends a PUT request to the Lunchmoney API with the transaction_id and update fields.

  async ({ transaction_id, update, update_balance }) => {
      try {
          const path =
              update_balance === undefined
                  ? `/transactions/${transaction_id}`
                  : `/transactions/${transaction_id}?update_balance=${update_balance}`;
          const response = await api.put(path, update);
  
          if (!response.ok) {
              return handleApiError(
                  response,
                  "Failed to update transaction",
              );
          }
  
          return dataResponse(await response.json());
      } catch (error) {
          return catchError(error, "Failed to update transaction");
      }
  },

• src/tools/transactions.ts:370-413 (registration)

  Registration of the 'update_transaction' tool on the MCP server, including description, input schema, and annotations.

  server.registerTool(
      "update_transaction",
      {
          description:
              "Update an existing transaction. Provide any subset of writable fields directly (the v2 API no longer wraps the body in a `transaction` envelope). Cannot modify split or grouped transactions; use the corresponding split/group tools instead.",
          inputSchema: {
              transaction_id: z.coerce
                  .number()
                  .describe("ID of the transaction to update."),
              update: updateTransactionFieldsSchema.describe(
                  "Fields to update. Provide at least one writable field.",
              ),
              update_balance: z
                  .boolean()
                  .optional()
                  .describe(
                      "Defaults to true. Pass false to skip updating the associated manual account's balance.",
                  ),
          },
          annotations: {
              idempotentHint: true,
          },
      },
      async ({ transaction_id, update, update_balance }) => {
          try {
              const path =
                  update_balance === undefined
                      ? `/transactions/${transaction_id}`
                      : `/transactions/${transaction_id}?update_balance=${update_balance}`;
              const response = await api.put(path, update);
  
              if (!response.ok) {
                  return handleApiError(
                      response,
                      "Failed to update transaction",
                  );
              }
  
              return dataResponse(await response.json());
          } catch (error) {
              return catchError(error, "Failed to update transaction");
          }
      },
  );

• src/api.ts:146-150 (helper)

  The api.put() helper used by the handler to make the PUT request to the Lunchmoney API.

  export const api = {
      get: (path: string) => apiRequest("GET", path),
      post: (path: string, body?: unknown) => apiRequest("POST", path, body),
      put: (path: string, body: unknown) => apiRequest("PUT", path, body),
      delete: (path: string, body?: unknown) => apiRequest("DELETE", path, body),